@gzl10/baserow 1.2.0

package/src/services/RowService.ts

@@ -0,0 +1,982 @@
+import { HttpService } from './core/HttpService'
+import { ValidationService } from './core/ValidationService'
+import {
+  Row,
+  CreateRowRequest,
+  UpdateRowRequest,
+  QueryOptions,
+  BulkOptions,
+  BaserowResponse,
+  BaserowNotFoundError,
+  Logger
+} from '../types/index'
+import { chunkArray, delay } from '../utils/validation'
+
+/**
+ * Servicio para operaciones CRUD de filas de Baserow
+ *
+ * Proporciona operaciones completas de filas incluyendo CRUD básico,
+ * operaciones bulk optimizadas y métodos de utilidad avanzados.
+ * Maneja paginación automática, rate limiting y validación robusta.
+ *
+ * **Características:**
+ * - CRUD completo: create, read, update, delete
+ * - Operaciones bulk optimizadas con chunking automático
+ * - `listAll()` con paginación automática para descargar tablas completas
+ * - Rate limiting automático entre requests
+ * - Validación de datos y IDs
+ * - Manejo robusto de errores
+ *
+ * @example
+ * ```typescript
+ * // Operaciones básicas
+ * const rows = await rowService.list(tableId, { size: 50 })
+ * const row = await rowService.get(tableId, rowId)
+ * const newRow = await rowService.createRow(tableId, { name: 'John', email: 'john@example.com' })
+ * await rowService.updateRow(tableId, rowId, { name: 'Jane' })
+ * await rowService.delete(tableId, rowId)
+ *
+ * // Operaciones bulk
+ * const allRows = await rowService.listAll(tableId) // Descarga tabla completa
+ * const createdRows = await rowService.createBulk(tableId, [
+ *   { name: 'Alice', email: 'alice@example.com' },
+ *   { name: 'Bob', email: 'bob@example.com' }
+ * ])
+ * ```
+ *
+ * @since 1.0.0
+ */
+export class RowService extends HttpService {
+  private validationService: ValidationService
+
+  constructor(http: any, logger?: Logger) {
+    super(http, logger)
+    this.validationService = new ValidationService(http, logger)
+  }
+
+  /**
+   * Obtener filas de una tabla con opciones de filtrado y paginación
+   *
+   * Lista filas de una tabla específica con soporte completo para filtrado,
+   * ordenamiento, búsqueda y paginación. Retorna metadatos de paginación.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param options - Opciones de consulta
+   * @param options.page - Número de página (default: 1)
+   * @param options.size - Tamaño de página (default: 100)
+   * @param options.search - Término de búsqueda en todos los campos
+   * @param options.order_by - Campo para ordenar (prefijo '-' para desc)
+   * @param options.filters - Filtros por campo específico
+   * @param options.user_field_names - Usar nombres de usuario para campos (default: true)
+   * @returns Promise con filas y metadatos de paginación
+   *
+   * @throws {BaserowValidationError} Si el tableId es inválido
+   *
+   * @example
+   * ```typescript
+   * // Lista básica
+   * const result = await rowService.list(123)
+   * console.log(`${result.count} filas total, mostrando ${result.rows.length}`)
+   *
+   * // Con filtros y ordenamiento
+   * const filtered = await rowService.list(123, {
+   *   search: 'John',
+   *   order_by: '-created_at',
+   *   filters: { status: 'active' },
+   *   size: 50
+   * })
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async list(
+    tableId: number,
+    options: QueryOptions = {}
+  ): Promise<{
+    rows: Row[]
+    count: number
+    next: string | null
+    previous: string | null
+  }> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    const params: any = {
+      user_field_names: options.user_field_names ?? true,
+      ...options
+    }
+
+    // Aplanar filtros directamente en query params para Baserow API
+    if (options.filters && typeof options.filters === 'object' && Object.keys(options.filters).length > 0) {
+      Object.assign(params, options.filters)
+      delete params.filters // No enviar el objeto anidado
+    }
+
+    // Preservar filter_type si existe (para OR queries)
+    if (options.filter_type) {
+      params.filter_type = options.filter_type
+    }
+
+    try {
+      this.logDebug(`Fetching rows from table ${tableId}`, options)
+      this.logDebug(`Final query params being sent to Baserow API:`, params)
+      const response = await this.http.get<BaserowResponse<Row>>(`/database/rows/table/${tableId}/`, params)
+
+      const result = {
+        rows: response.results,
+        count: response.count,
+        next: response.next,
+        previous: response.previous
+      }
+
+      this.logSuccess('list rows', tableId, { count: result.count, pageSize: result.rows.length })
+      return result
+    } catch (error) {
+      this.handleHttpError(error, 'list rows', tableId)
+    }
+  }
+
+  /**
+   * Obtener todas las filas de una tabla (maneja paginación automáticamente)
+   *
+   * Descarga la tabla completa manejando paginación automáticamente.
+   * Ideal para exportar datos o análisis completo de tablas.
+   * Incluye rate limiting automático entre páginas.
+   *
+   * @aiUsage
+   * **✅ Usar cuando:**
+   * - Necesitas exportar/analizar la tabla completa (< 50K filas)
+   * - Generar reportes o backups completos
+   * - Sincronización de datos entre sistemas
+   * - Análisis de datos que requiere dataset completo
+   *
+   * **❌ NO usar cuando:**
+   * - Tabla tiene > 50K filas (alto consumo de memoria)
+   * - Solo necesitas primeras N filas (usa `list()` con paginación)
+   * - Datos cambian frecuentemente durante la carga (inconsistencias)
+   * - Aplicación tiene límites de memoria estrictos
+   *
+   * @aiWarning
+   * **⚠️ Consumo de Memoria:**
+   * - Cada fila ocupa ~1-5 KB en memoria (depende de campos)
+   * - 10,000 filas ≈ 10-50 MB
+   * - 50,000 filas ≈ 50-250 MB
+   * - 100,000+ filas → ⚠️ Posible OutOfMemory en Node.js
+   *
+   * **⚠️ Tiempo de Ejecución:**
+   * - ~200 filas/segundo (aprox. 5 páginas/segundo con pageSize=200)
+   * - 10,000 filas → ~50 segundos
+   * - 50,000 filas → ~4-5 minutos
+   *
+   * @aiAlternative
+   * **Para tablas grandes (>50K filas), usa paginación manual:**
+   * ```typescript
+   * // Procesar en streaming sin cargar todo en memoria
+   * let page = 1
+   * while (true) {
+   *   const result = await rowService.list(tableId, { page, size: 200 })
+   *
+   *   // Procesar chunk inmediatamente
+   *   await processChunk(result.rows)
+   *
+   *   if (!result.next) break
+   *   page++
+   * }
+   * ```
+   *
+   * @aiPerformance
+   * **Optimizaciones:**
+   * - `size: 200` (default) → Balance ideal entre requests y memoria
+   * - `delay: 50ms` (default) → Evita rate limiting
+   * - Para tablas pequeñas (<5K): aumentar `size: 500` y reducir `delay: 0`
+   * - Para tablas grandes (>20K): reducir `size: 100` y aumentar `delay: 100ms`
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param options - Opciones de consulta (sin page/size)
+   * @param options.search - Término de búsqueda
+   * @param options.order_by - Campo para ordenar
+   * @param options.filters - Filtros por campo
+   * @param options.delay - Delay entre páginas en ms (default: 50)
+   * @param options.size - Tamaño de página interna (default: 200)
+   * @returns Promise con array de todas las filas
+   *
+   * @throws {BaserowValidationError} Si el tableId es inválido
+   *
+   * @example
+   * ```typescript
+   * // Descargar tabla completa
+   * const allRows = await rowService.listAll(123)
+   * console.log(`Descargadas ${allRows.length} filas`)
+   *
+   * // Con filtros aplicados
+   * const activeUsers = await rowService.listAll(123, {
+   *   filters: { status: 'active' },
+   *   order_by: 'name'
+   * })
+   *
+   * // Optimizado para tabla grande (>20K filas)
+   * const allRows = await rowService.listAll(123, {
+   *   size: 100,  // Chunks más pequeños
+   *   delay: 100  // Más tiempo entre requests
+   * })
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async listAll(tableId: number, options: Omit<QueryOptions, 'page' | 'size'> = {}): Promise<Row[]> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    const allRows: Row[] = []
+    let page = 1
+    const size = (options as any).size || 200 // Tamaño de página configurable
+
+    this.logInfo(`Starting listAll for table ${tableId}`, { pageSize: size })
+
+    while (true) {
+      const result = await this.list(tableId, {
+        ...options,
+        page,
+        size
+      })
+
+      allRows.push(...result.rows)
+      this.logDebug(`Fetched page ${page}`, { rowsThisPage: result.rows.length, totalRows: allRows.length })
+
+      if (!result.next) {
+        break
+      }
+
+      page++
+      await delay((options as any).delay || 50) // Rate limiting configurable
+    }
+
+    this.logSuccess('listAll completed', tableId, { totalRows: allRows.length, pages: page })
+    return allRows
+  }
+
+  /**
+   * Obtener fila específica por ID
+   *
+   * Recupera una fila individual por su ID con datos completos.
+   * Útil para operaciones de lectura específicas.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param rowId - ID numérico de la fila
+   * @param userFieldNames - Usar nombres de usuario para campos (default: true)
+   * @returns Promise con datos completos de la fila
+   *
+   * @throws {BaserowNotFoundError} Si la fila no existe
+   * @throws {BaserowValidationError} Si los IDs son inválidos
+   *
+   * @example
+   * ```typescript
+   * const row = await rowService.get(123, 456)
+   * console.log(`Usuario: ${row.name} - ${row.email}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async get(tableId: number, rowId: number, userFieldNames = true): Promise<Row> {
+    this.validationService.validateId(tableId, 'table ID')
+    this.validationService.validateId(rowId, 'row ID')
+
+    try {
+      this.logDebug(`Fetching row ${rowId} from table ${tableId}`, { userFieldNames })
+      const response = await this.http.get<Row>(`/database/rows/table/${tableId}/${rowId}/`, {
+        user_field_names: userFieldNames
+      })
+      this.logSuccess('get row', rowId)
+      return response
+    } catch (error) {
+      if ((error as any).status === 404) {
+        throw new BaserowNotFoundError('Row', rowId)
+      }
+      this.handleHttpError(error, 'get row', rowId)
+    }
+  }
+
+  /**
+   * Crear nueva fila
+   *
+   * Crea una nueva fila en la tabla especificada con los datos proporcionados.
+   * Valida tipos de datos y estructura según el esquema de la tabla.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param data - Datos de la nueva fila (usar nombres de campo de usuario)
+   * @returns Promise con la fila creada (incluye ID asignado)
+   *
+   * @throws {BaserowValidationError} Si los datos son inválidos
+   *
+   * @example
+   * ```typescript
+   * const newRow = await rowService.createRow(123, {
+   *   name: 'John Doe',
+   *   email: 'john@example.com',
+   *   age: 30,
+   *   active: true
+   * })
+   * console.log(`Fila creada con ID: ${newRow.id}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async createRow(tableId: number, data: CreateRowRequest): Promise<Row> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    if (!data || typeof data !== 'object') {
+      throw new Error('Row data is required and must be an object')
+    }
+
+    try {
+      this.logDebug(`Creating row in table ${tableId}`, data)
+      const response = await this.http.post<Row>(`/database/rows/table/${tableId}/`, data, {
+        user_field_names: true
+      })
+
+      this.logSuccess('create row', response.id)
+      return { ...response, id: response.id }
+    } catch (error) {
+      this.handleHttpError(error, 'create row', tableId)
+    }
+  }
+
+  /**
+   * Actualizar fila existente
+   *
+   * Actualiza una fila existente con nuevos datos. Solo actualiza
+   * los campos proporcionados (actualización parcial).
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param rowId - ID numérico de la fila a actualizar
+   * @param data - Datos a actualizar (solo campos modificados)
+   * @returns Promise con la fila actualizada
+   *
+   * @throws {BaserowNotFoundError} Si la fila no existe
+   * @throws {BaserowValidationError} Si los datos son inválidos
+   *
+   * @example
+   * ```typescript
+   * const updatedRow = await rowService.updateRow(123, 456, {
+   *   email: 'newemail@example.com',
+   *   active: false
+   * })
+   * console.log(`Fila actualizada: ${updatedRow.name}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async updateRow(tableId: number, rowId: number, data: UpdateRowRequest): Promise<Row> {
+    this.validationService.validateId(tableId, 'table ID')
+    this.validationService.validateId(rowId, 'row ID')
+
+    if (!data || typeof data !== 'object') {
+      throw new Error('Row data is required and must be an object')
+    }
+
+    try {
+      this.logDebug(`Updating row ${rowId} in table ${tableId}`, data)
+      const response = await this.http.patch<Row>(`/database/rows/table/${tableId}/${rowId}/`, data, {
+        user_field_names: true
+      })
+      this.logSuccess('update row', rowId)
+      return response
+    } catch (error) {
+      if ((error as any).status === 404) {
+        throw new BaserowNotFoundError('Row', rowId)
+      }
+      this.handleHttpError(error, 'update row', rowId)
+    }
+  }
+
+  /**
+   * Eliminar fila
+   *
+   * Elimina permanentemente una fila de la tabla.
+   * Esta operación no se puede deshacer.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param rowId - ID numérico de la fila a eliminar
+   * @returns Promise que resuelve cuando la fila es eliminada
+   *
+   * @throws {BaserowNotFoundError} Si la fila no existe
+   * @throws {BaserowValidationError} Si los IDs son inválidos
+   *
+   * @example
+   * ```typescript
+   * await rowService.delete(123, 456)
+   * console.log('Fila eliminada exitosamente')
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async delete(tableId: number, rowId: number): Promise<void> {
+    this.validationService.validateId(tableId, 'table ID')
+    this.validationService.validateId(rowId, 'row ID')
+
+    try {
+      this.logDebug(`Deleting row ${rowId} from table ${tableId}`)
+      await this.http.delete(`/database/rows/table/${tableId}/${rowId}/`)
+      this.logSuccess('delete row', rowId)
+    } catch (error) {
+      if ((error as any).status === 404) {
+        throw new BaserowNotFoundError('Row', rowId)
+      }
+      this.handleHttpError(error, 'delete row', rowId)
+    }
+  }
+
+  // ===== OPERACIONES BULK =====
+
+  /**
+   * Crear múltiples filas en lotes (bulk create)
+   *
+   * Crea múltiples filas de forma eficiente usando operaciones batch.
+   * Procesa en chunks para optimizar rendimiento y evitar timeouts.
+   * Incluye rate limiting automático entre lotes.
+   *
+   * @aiUsage
+   * **✅ Usar cuando:**
+   * - Importar datos desde CSV, JSON o bases de datos externas
+   * - Migración de datos entre tablas o sistemas
+   * - Seed de datos de prueba o inicialización
+   * - Inserción masiva desde formularios o APIs (>10 filas)
+   *
+   * **❌ NO usar cuando:**
+   * - Solo 1-5 filas → Usar `createRow()` individual (más simple)
+   * - Necesitas validación compleja fila por fila (usa loop con try/catch)
+   * - Datos vienen de stream continuo (procesar en mini-batches)
+   *
+   * @aiPerformance
+   * **Tamaño de Batch Óptimo (batchSize):**
+   * - `100-200` → **Recomendado general** (balance velocidad/confiabilidad)
+   * - `50-100` → Conexiones lentas o datos complejos (muchos campos)
+   * - `200-500` → Conexiones rápidas y datos simples (pocos campos)
+   * - `> 500` → ⚠️ Riesgo de timeout en Baserow API
+   *
+   * **Rendimiento Estimado:**
+   * - ~1,000 filas/minuto con batchSize=200 (velocidad promedio)
+   * - 10,000 filas → ~10 minutos
+   * - 50,000 filas → ~50 minutos
+   *
+   * @aiErrorHandling
+   * **Manejo de Errores Parciales:**
+   * ```typescript
+   * // Si un batch falla, TODA la operación se detiene
+   * try {
+   *   const created = await rowService.createBulk(tableId, rows, { batchSize: 100 })
+   *   console.log(`✅ ${created.length} filas creadas`)
+   * } catch (error) {
+   *   console.error('❌ Error en batch, algunas filas pueden haberse creado')
+   *   // Verificar cuántas filas se crearon antes del error
+   *   const currentCount = await rowService.count(tableId)
+   *   console.log(`Total filas actuales: ${currentCount}`)
+   * }
+   * ```
+   *
+   * **Para operaciones críticas, considera transacciones manuales:**
+   * ```typescript
+   * const created = []
+   * const failed = []
+   *
+   * for (const chunk of chunks(rows, 100)) {
+   *   try {
+   *     const result = await rowService.createBulk(tableId, chunk, { batchSize: 100 })
+   *     created.push(...result)
+   *   } catch (error) {
+   *     failed.push({ chunk, error })
+   *     // Continuar o abortar según lógica de negocio
+   *   }
+   * }
+   *
+   * console.log(`Creadas: ${created.length}, Fallidas: ${failed.length}`)
+   * ```
+   *
+   * @aiWarning
+   * **⚠️ Webhooks Deshabilitados por Default:**
+   * - `send_webhook_events: false` (default) → Sin notificaciones
+   * - Para habilitar webhooks: `{ send_webhook_events: true }`
+   * - ⚠️ Con webhooks habilitados, la operación es ~20-30% más lenta
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param rows - Array de datos para crear filas
+   * @param options - Opciones de la operación bulk
+   * @param options.batchSize - Tamaño de lote (default: 200)
+   * @param options.send_webhook_events - Enviar eventos webhook (default: false)
+   * @param options.user_field_names - Usar nombres de usuario (default: true)
+   * @returns Promise con array de filas creadas
+   *
+   * @throws {BaserowValidationError} Si los datos son inválidos
+   *
+   * @example
+   * ```typescript
+   * // Importación básica
+   * const newRows = await rowService.createBulk(123, [
+   *   { name: 'Alice', email: 'alice@example.com' },
+   *   { name: 'Bob', email: 'bob@example.com' },
+   *   // ... más filas
+   * ], { batchSize: 100 })
+   * console.log(`${newRows.length} filas creadas`)
+   *
+   * // Con webhooks habilitados (notificaciones activas)
+   * const created = await rowService.createBulk(tableId, rows, {
+   *   batchSize: 150,
+   *   send_webhook_events: true
+   * })
+   *
+   * // Importación desde CSV con logging
+   * const csvData = await parseCsv('data.csv')
+   * console.log(`Importando ${csvData.length} filas...`)
+   *
+   * const imported = await rowService.createBulk(tableId, csvData, {
+   *   batchSize: 200
+   * })
+   *
+   * console.log(`✅ Importadas ${imported.length} de ${csvData.length} filas`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async createBulk(tableId: number, rows: CreateRowRequest[], options: BulkOptions = {}): Promise<Row[]> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    if (!rows || !Array.isArray(rows) || rows.length === 0) {
+      throw new Error('Rows must be a non-empty array')
+    }
+
+    const { batchSize = 200, send_webhook_events = false, user_field_names = true } = options
+
+    const chunks = chunkArray(rows, batchSize)
+    const results: Row[] = []
+
+    this.logger?.info('🔧 Bulk create iniciado', { tableId, rowCount: rows.length, batchCount: chunks.length })
+
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i]
+      const batchNum = i + 1
+
+      try {
+        this.logger?.info('Procesando lote', { batchNum, totalBatches: chunks.length, batchSize: chunk.length })
+
+        const response = await this.http.post<{ items: Row[] }>(
+          `/database/rows/table/${tableId}/batch/`,
+          { items: chunk },
+          {
+            user_field_names,
+            send_webhook_events
+          }
+        )
+
+        results.push(...(response.items || []))
+
+        // Rate limiting entre lotes
+        if (i < chunks.length - 1) {
+          await delay(100)
+        }
+
+        this.logger?.info('Lote procesado correctamente', { batchNum })
+      } catch (error) {
+        this.logger?.error('❌ Error en lote', { batchNum, totalBatches: chunks.length, error })
+        throw error
+      }
+    }
+
+    this.logger?.info('✅ Bulk create completado', { createdRows: results.length })
+    return results
+  }
+
+  /**
+   * Actualizar múltiples filas en lotes (bulk update)
+   *
+   * Actualiza múltiples filas de forma eficiente usando operaciones batch.
+   * Cada elemento del array debe incluir el ID de la fila a actualizar.
+   * Procesa en chunks con rate limiting automático.
+   *
+   * @aiUsage
+   * **✅ Usar cuando:**
+   * - Actualizar estado/status de múltiples registros (ej: marcar como procesado)
+   * - Sincronización de datos desde sistema externo (>10 filas)
+   * - Actualizar campos calculados en batch (ej: recalcular totales)
+   * - Operaciones administrativas masivas (cambiar propietario, categoría, etc.)
+   *
+   * **❌ NO usar cuando:**
+   * - Solo 1-5 filas → Usar `updateRow()` individual
+   * - Updates dependen de estado previo (race conditions) → Actualizar secuencialmente
+   * - Necesitas rollback complejo → Implementar transacciones manuales
+   *
+   * @aiPerformance
+   * **Igual que `createBulk()`:**
+   * - **Batch Size Recomendado:** 100-200 filas
+   * - **Rendimiento:** ~1,000 actualizaciones/minuto
+   *
+   * @aiErrorHandling
+   * **Validación Estricta de IDs:**
+   * ```typescript
+   * // ❌ INCORRECTO - Faltan IDs
+   * await rowService.updateBulk(tableId, [
+   *   { status: 'active' }  // Error: falta 'id'
+   * ])
+   *
+   * // ✅ CORRECTO - Cada update tiene su ID
+   * await rowService.updateBulk(tableId, [
+   *   { id: 1, status: 'active' },
+   *   { id: 2, status: 'inactive' }
+   * ])
+   * ```
+   *
+   * **Manejo de Errores con Rollback Parcial:**
+   * ```typescript
+   * const updates = [...] // Array grande de updates
+   * const originalValues = await rowService.listAll(tableId) // Backup
+   *
+   * try {
+   *   const updated = await rowService.updateBulk(tableId, updates, { batchSize: 100 })
+   *   console.log(`✅ ${updated.length} filas actualizadas`)
+   * } catch (error) {
+   *   console.error('❌ Error durante update, iniciando rollback...')
+   *
+   *   // Rollback manual de filas afectadas
+   *   const rollbackData = originalValues.map(row => ({
+   *     id: row.id,
+   *     ...pickFields(row, changedFields)
+   *   }))
+   *
+   *   await rowService.updateBulk(tableId, rollbackData)
+   *   console.log('Rollback completado')
+   * }
+   * ```
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param updates - Array de actualizaciones (cada una debe incluir 'id')
+   * @param options - Opciones de la operación bulk
+   * @param options.batchSize - Tamaño de lote (default: 200)
+   * @param options.send_webhook_events - Enviar eventos webhook (default: false)
+   * @param options.user_field_names - Usar nombres de usuario (default: true)
+   * @returns Promise con array de filas actualizadas
+   *
+   * @throws {BaserowValidationError} Si faltan IDs o datos son inválidos
+   *
+   * @example
+   * ```typescript
+   * // Actualización básica de status
+   * const updates = [
+   *   { id: 1, status: 'active' },
+   *   { id: 2, status: 'inactive' },
+   *   { id: 3, email: 'updated@example.com' }
+   * ]
+   *
+   * const updatedRows = await rowService.updateBulk(123, updates)
+   * console.log(`${updatedRows.length} filas actualizadas`)
+   *
+   * // Actualizar desde sistema externo
+   * const externalData = await fetchFromAPI()
+   * const updates = externalData.map(item => ({
+   *   id: item.baserowId,
+   *   name: item.fullName,
+   *   email: item.emailAddress,
+   *   updated_at: new Date().toISOString()
+   * }))
+   *
+   * await rowService.updateBulk(tableId, updates, { batchSize: 150 })
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async updateBulk(
+    tableId: number,
+    updates: Array<{ id: number } & UpdateRowRequest>,
+    options: BulkOptions = {}
+  ): Promise<Row[]> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    if (!updates || !Array.isArray(updates) || updates.length === 0) {
+      throw new Error('Updates must be a non-empty array')
+    }
+
+    // Validar que todas las actualizaciones tienen ID
+    updates.forEach((update, index) => {
+      if (!update.id || typeof update.id !== 'number' || update.id <= 0) {
+        throw new Error(`Update at index ${index} must have a valid id`)
+      }
+    })
+
+    const { batchSize = 200, send_webhook_events = false, user_field_names = true } = options
+
+    const chunks = chunkArray(updates, batchSize)
+    const results: Row[] = []
+
+    this.logger?.info('Bulk update iniciado', { tableId, updateCount: updates.length, batchCount: chunks.length })
+
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i]
+      const batchNum = i + 1
+
+      try {
+        this.logger?.info('Procesando lote', { batchNum, totalBatches: chunks.length, batchSize: chunk.length })
+
+        const response = await this.http.patch<{ items: Row[] }>(
+          `/database/rows/table/${tableId}/batch/`,
+          { items: chunk },
+          {
+            user_field_names,
+            send_webhook_events
+          }
+        )
+
+        results.push(...(response.items || []))
+
+        // Rate limiting entre lotes
+        if (i < chunks.length - 1) {
+          await delay(100)
+        }
+
+        this.logger?.info('Lote procesado correctamente', { batchNum })
+      } catch (error) {
+        this.logger?.error('❌ Error en lote', { batchNum, totalBatches: chunks.length, error })
+        throw error
+      }
+    }
+
+    this.logger?.info('Bulk update completado', { updatedRows: results.length })
+    return results
+  }
+
+  /**
+   * Eliminar múltiples filas
+   *
+   * Elimina múltiples filas de forma eficiente. Procesa en lotes pequeños
+   * para evitar problemas con URLs muy largas. Operación irreversible.
+   *
+   * @aiUsage
+   * **✅ Usar cuando:**
+   * - Limpieza de datos obsoletos (registros antiguos, duplicados)
+   * - Eliminación administrativa masiva (purgar test data)
+   * - Sincronización: eliminar filas que ya no existen en origen
+   * - Operaciones de mantenimiento (>10 filas)
+   *
+   * **❌ NO usar cuando:**
+   * - Solo 1-5 filas → Usar `delete()` individual
+   * - Datos pueden recuperarse → Considerar soft delete (campo deleted=true)
+   * - Operación puede fallar parcialmente → Implementar backup previo
+   *
+   * @aiWarning
+   * **⚠️ OPERACIÓN IRREVERSIBLE:**
+   * - **NO hay undo/rollback automático** en Baserow
+   * - Una vez eliminadas, las filas NO se pueden recuperar
+   * - Si la operación falla a mitad, algunas filas YA estarán eliminadas
+   *
+   * **⚠️ Batch Size Pequeño (50 default):**
+   * - Usa batchSize=50 (más pequeño que create/update) para evitar URLs largas
+   * - Baserow API usa DELETE con query params: `/table/123/1,2,3,4,5...`
+   * - URLs muy largas (>2000 chars) pueden fallar en algunos proxies
+   *
+   * @aiErrorHandling
+   * **Patrón de Backup Preventivo:**
+   * ```typescript
+   * // ✅ RECOMENDADO: Backup antes de eliminar
+   * const rowsToDelete = [1, 2, 3, 4, 5]
+   *
+   * // 1. Crear backup de las filas
+   * const backup = await Promise.all(
+   *   rowsToDelete.map(id => rowService.get(tableId, id))
+   * )
+   * console.log(`Backup creado: ${backup.length} filas`)
+   *
+   * // 2. Guardar backup en archivo o DB
+   * await fs.writeFile('backup.json', JSON.stringify(backup, null, 2))
+   *
+   * // 3. Eliminar filas
+   * try {
+   *   await rowService.deleteBulk(tableId, rowsToDelete)
+   *   console.log('✅ Eliminación exitosa')
+   * } catch (error) {
+   *   console.error('❌ Error durante eliminación')
+   *   console.log('Backup disponible en backup.json para restauración manual')
+   *   throw error
+   * }
+   * ```
+   *
+   * **Confirmación Interactiva para Operaciones Peligrosas:**
+   * ```typescript
+   * async function safeBulkDelete(tableId: number, rowIds: number[]) {
+   *   console.log(`⚠️  Vas a eliminar ${rowIds.length} filas de forma PERMANENTE`)
+   *
+   *   const confirmed = await promptUser('¿Estás seguro? (yes/no): ')
+   *   if (confirmed !== 'yes') {
+   *     console.log('Operación cancelada')
+   *     return
+   *   }
+   *
+   *   const backup = await createBackup(tableId, rowIds)
+   *   console.log(`Backup creado: ${backup.length} filas`)
+   *
+   *   await rowService.deleteBulk(tableId, rowIds)
+   *   console.log('✅ Eliminación completada')
+   * }
+   * ```
+   *
+   * @aiPerformance
+   * **Rendimiento de Deletes:**
+   * - Más lento que create/update (eliminación paralela en chunks)
+   * - ~500-800 eliminaciones/minuto con batchSize=50
+   * - 10,000 filas → ~12-20 minutos
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param rowIds - Array de IDs de filas a eliminar
+   * @param options - Opciones de la operación
+   * @param options.batchSize - Tamaño de lote (default: 50)
+   * @returns Promise que resuelve cuando todas las filas son eliminadas
+   *
+   * @throws {BaserowValidationError} Si los IDs son inválidos
+   * @throws {BaserowNotFoundError} Si alguna fila no existe
+   *
+   * @example
+   * ```typescript
+   * // Eliminación básica
+   * const idsToDelete = [123, 456, 789]
+   * await rowService.deleteBulk(tableId, idsToDelete)
+   * console.log(`${idsToDelete.length} filas eliminadas`)
+   *
+   * // Con backup preventivo
+   * const rowsToDelete = await rowService.list(tableId, {
+   *   filters: { status: 'archived' }
+   * })
+   *
+   * const backup = rowsToDelete.rows
+   * await fs.writeFile('archived_backup.json', JSON.stringify(backup))
+   *
+   * const ids = rowsToDelete.rows.map(r => r.id)
+   * await rowService.deleteBulk(tableId, ids, { batchSize: 50 })
+   *
+   * console.log(`✅ ${ids.length} filas archivadas eliminadas (backup guardado)`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async deleteBulk(tableId: number, rowIds: number[], options?: BulkOptions): Promise<void> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    if (!rowIds || !Array.isArray(rowIds) || rowIds.length === 0) {
+      throw new Error('Row IDs must be a non-empty array')
+    }
+
+    rowIds.forEach(id => this.validationService.validateId(id, 'row ID'))
+
+    // Eliminar en lotes más pequeños para evitar problemas con URLs muy largas
+    const deleteBatchSize = options?.batchSize || 50
+    const chunks = chunkArray(rowIds, deleteBatchSize)
+
+    this.logger?.info('Bulk delete iniciado', { tableId, deleteCount: rowIds.length, batchCount: chunks.length })
+
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i]
+      const batchNum = i + 1
+
+      try {
+        this.logger?.info('Procesando lote', { batchNum, totalBatches: chunks.length, batchSize: chunk.length })
+
+        // Eliminar una por una en paralelo (más eficiente que secuencial)
+        await Promise.all(chunk.map(rowId => this.delete(tableId, rowId)))
+
+        // Rate limiting entre lotes
+        if (i < chunks.length - 1) {
+          await delay(200)
+        }
+
+        this.logger?.info('Lote procesado correctamente', { batchNum })
+      } catch (error) {
+        this.logger?.error('❌ Error en lote', { batchNum, totalBatches: chunks.length, error })
+        throw error
+      }
+    }
+
+    this.logger?.info('Bulk delete completado', { deletedRows: rowIds.length })
+  }
+
+  /**
+   * Buscar filas por criterios específicos
+   *
+   * Método de conveniencia para buscar filas usando un término de búsqueda.
+   * Busca en todos los campos de texto de la tabla.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param query - Término de búsqueda
+   * @param options - Opciones adicionales de consulta (sin search)
+   * @returns Promise con array de filas que coinciden
+   *
+   * @example
+   * ```typescript
+   * const results = await rowService.search(123, 'john', {
+   *   order_by: 'name',
+   *   size: 20
+   * })
+   * console.log(`Encontradas ${results.length} filas`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async search(tableId: number, query: string, options: Omit<QueryOptions, 'search'> = {}): Promise<Row[]> {
+    return (await this.list(tableId, { ...options, search: query })).rows
+  }
+
+  /**
+   * Verificar si una fila existe
+   *
+   * Verifica la existencia de una fila sin cargar todos sus datos.
+   * Útil para validaciones antes de operaciones.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param rowId - ID numérico de la fila
+   * @returns Promise que resuelve a true si existe, false si no
+   *
+   * @example
+   * ```typescript
+   * const exists = await rowService.exists(123, 456)
+   * if (exists) {
+   *   console.log('La fila existe')
+   * } else {
+   *   console.log('La fila no existe')
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async exists(tableId: number, rowId: number): Promise<boolean> {
+    try {
+      await this.get(tableId, rowId)
+      return true
+    } catch (error) {
+      if (error instanceof BaserowNotFoundError) {
+        return false
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Contar filas en una tabla
+   *
+   * Obtiene el número total de filas en una tabla, opcionalmente
+   * aplicando filtros. No carga los datos de las filas.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @param filters - Filtros opcionales para aplicar al conteo
+   * @returns Promise con el número total de filas
+   *
+   * @example
+   * ```typescript
+   * const total = await rowService.count(123)
+   * console.log(`Total de filas: ${total}`)
+   *
+   * const activeCount = await rowService.count(123, { status: 'active' })
+   * console.log(`Filas activas: ${activeCount}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async count(tableId: number, filters?: Record<string, any>): Promise<number> {
+    const result = await this.list(tableId, {
+      size: 1,
+      filters
+    })
+    return result.count
+  }
+}