@gzl10/baserow 1.2.0

package/src/services/TableService.ts

@@ -0,0 +1,781 @@
+import { HttpService } from './core/HttpService'
+import { ValidationService } from './core/ValidationService'
+import {
+  Table,
+  CreateTableRequest,
+  UpdateTableRequest,
+  BaserowResponse,
+  BaserowNotFoundError,
+  Field,
+  Logger,
+  TableFromAllTables
+} from '../types/index'
+
+/**
+ * Servicio para operaciones CRUD de tablas de Baserow
+ *
+ * Proporciona operaciones completas de tablas incluyendo CRUD básico,
+ * creación asíncrona, duplicación, reordenamiento y análisis de esquemas.
+ * Las tablas son contenedores de campos y filas en la jerarquía de Baserow.
+ *
+ * **Características:**
+ * - CRUD completo: create, read, update, delete
+ * - Creación síncrona y asíncrona (mejor para archivos grandes)
+ * - Búsqueda de tablas por nombre
+ * - Operaciones avanzadas: duplicar, reordenar
+ * - Análisis de esquemas y estadísticas
+ * - Validación de nombres y IDs
+ *
+ * **Jerarquía de Baserow:**
+ * ```
+ * Workspace → Database → Table → Field/Row
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Operaciones básicas
+ * const tables = await tableService.findMany(databaseId)
+ * const table = await tableService.get(tableId)
+ *
+ * // Buscar tabla por nombre o ID
+ * const found = await tableService.findUnique(databaseId, 'usuarios')
+ *
+ * // Crear tabla con datos iniciales
+ * const newTable = await tableService.create(databaseId, {
+ *   name: 'Usuarios',
+ *   data: [['Nombre', 'Email'], ['Juan', 'juan@example.com']],
+ *   first_row_header: true
+ * })
+ *
+ * // Operaciones avanzadas
+ * const duplicated = await tableService.duplicate(tableId, 'Copia de Usuarios')
+ * const stats = await tableService.getStats(tableId)
+ * ```
+ *
+ * @since 1.0.0
+ */
+export class TableService extends HttpService {
+  private validationService: ValidationService
+
+  constructor(http: any, logger?: Logger) {
+    super(http, logger)
+    this.validationService = new ValidationService(http, logger)
+  }
+
+  // ===== PUBLIC API (Prisma-style) =====
+
+  /**
+   * Listar todas las tablas de una database
+   *
+   * Obtiene todas las tablas de una database específica con sus metadatos.
+   * Incluye información de campos si está disponible en la respuesta.
+   *
+   * @param databaseId - ID numérico de la database
+   * @returns Promise con array de tablas
+   *
+   * @throws {BaserowValidationError} Si el databaseId es inválido
+   *
+   * @example
+   * ```typescript
+   * const tables = await tableService.findMany(123)
+   * tables.forEach(table => {
+   *   console.log(`${table.name} (ID: ${table.id})`)
+   * })
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async findMany(databaseId: number): Promise<Table[]> {
+    this.validationService.validateId(databaseId, 'database ID')
+
+    try {
+      const response = await this.http.get<BaserowResponse<Table> | Table[]>(`/database/tables/database/${databaseId}/`)
+
+      // La API puede devolver array directo o {results: []}
+      const tables = Array.isArray(response) ? response : response.results || []
+      this.logSuccess('find many tables', databaseId, { count: tables.length })
+      return tables
+    } catch (error) {
+      this.handleHttpError(error, 'find many tables', databaseId)
+    }
+  }
+
+  /**
+   * Obtener tabla por ID
+   *
+   * Recupera una tabla específica por su ID con metadatos completos.
+   * Útil para obtener información detallada de una tabla.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @returns Promise con datos completos de la tabla
+   *
+   * @throws {BaserowNotFoundError} Si la tabla no existe
+   * @throws {BaserowValidationError} Si el tableId es inválido
+   *
+   * @example
+   * ```typescript
+   * const table = await tableService.get(456)
+   * console.log(`Tabla: ${table.name} - Database: ${table.database_id}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async get(tableId: number): Promise<Table> {
+    this.validationService.validateId(tableId, 'table ID')
+    return this.getById<Table>('/database/tables', tableId)
+  }
+
+  /**
+   * Buscar tabla por ID o nombre en una database
+   *
+   * Busca una tabla específica por su ID o nombre dentro de una database.
+   * Útil para operaciones dinámicas donde se conoce el identificador pero no se sabe si es ID o nombre.
+   *
+   * @param databaseId - ID numérico de la database
+   * @param identifier - ID numérico o nombre de la tabla a buscar
+   * @returns Promise con la tabla encontrada o null si no existe
+   *
+   * @throws {BaserowValidationError} Si los parámetros son inválidos
+   *
+   * @example
+   * ```typescript
+   * const table = await tableService.findUnique(123, 'usuarios')
+   * if (table) {
+   *   console.log(`Tabla encontrada: ${table.id}`)
+   * } else {
+   *   console.log('Tabla no encontrada')
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async findUnique(databaseId: number, identifier: string | number): Promise<Table | null> {
+    this.validationService.validateId(databaseId, 'database ID')
+
+    if (typeof identifier === 'number') {
+      // Buscar por ID
+      try {
+        return await this.get(identifier)
+      } catch (error) {
+        if (error instanceof BaserowNotFoundError) {
+          return null
+        }
+        throw error
+      }
+    } else {
+      // Buscar por nombre
+      this.validationService.validateResourceName(identifier, 'table')
+      const tables = await this.findMany(databaseId)
+      const found = tables.find(table => table.name === identifier) || null
+
+      if (found) {
+        this.logSuccess(`find table by name "${identifier}"`, found.id)
+      } else {
+        this.logDebug(`No table found with name "${identifier}" in database ${databaseId}`)
+      }
+
+      return found
+    }
+  }
+
+  /**
+   * Crear nueva tabla - API pública
+   *
+   * Crea una nueva tabla en la database especificada. Soporta creación
+   * con datos iniciales y configuración de esquema. Modo síncrono ideal
+   * para tablas pequeñas y medianas.
+   *
+   * **⚠️ Comportamiento importante de Baserow:**
+   * Cuando se crea una tabla SIN datos iniciales (`data` vacío o undefined),
+   * Baserow automáticamente agrega campos y filas de ejemplo. Esta librería
+   * **automáticamente limpia** este contenido usando `ensureTableEmpty()`
+   * para garantizar tablas mínimas (solo campo primario, 0 filas).
+   *
+   * **Nota**: Baserow NO permite eliminar el campo primario, por lo que las
+   * tablas "vacías" tendrán siempre 1 campo primario como mínimo.
+   *
+   * @param databaseId - ID numérico de la database
+   * @param data - Configuración de la tabla
+   * @param data.name - Nombre de la tabla
+   * @param data.data - Datos iniciales (array 2D, opcional)
+   * @param data.first_row_header - Primera fila como headers (default: false)
+   * @param data.skipDefaultCleanup - Saltarse limpieza automática del contenido por defecto de Baserow (default: false)
+   * @returns Promise con la tabla creada (garantizada mínima si no hay datos)
+   *
+   * @throws {BaserowValidationError} Si los datos son inválidos
+   *
+   * @example
+   * ```typescript
+   * // Tabla mínima (auto-limpiada)
+   * const emptyTable = await tableService.create(123, {
+   *   name: 'Nueva Tabla'
+   * })
+   * // Resultado: 1 campo primario, 0 filas (limpieza automática)
+   *
+   * // Tabla con contenido por defecto de Baserow (sin limpieza)
+   * const defaultTable = await tableService.create(123, {
+   *   name: 'Tabla con Defaults',
+   *   skipDefaultCleanup: true
+   * })
+   * // Resultado: campos y filas de ejemplo creados por Baserow
+   *
+   * // Tabla con datos iniciales (sin limpieza)
+   * const dataTable = await tableService.create(123, {
+   *   name: 'Usuarios',
+   *   data: [
+   *     ['Nombre', 'Email', 'Activo'],
+   *     ['Juan', 'juan@example.com', true],
+   *     ['María', 'maria@example.com', false]
+   *   ],
+   *   first_row_header: true
+   * })
+   * // Resultado: 3 campos, 2 filas (sin limpieza automática)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async create(databaseId: number, data: CreateTableRequest): Promise<Table> {
+    return this.createTableInternal(databaseId, data)
+  }
+
+  // ===== PRIVATE METHODS =====
+
+  /**
+   * Crear nueva tabla (método interno)
+   * @private - Solo para uso interno del servicio
+   */
+  private async createTableInternal(databaseId: number, data: CreateTableRequest): Promise<Table> {
+    this.validationService.validateId(databaseId, 'database ID')
+    this.validationService.validateResourceName(data.name, 'table')
+
+    try {
+      this.logDebug(`Creating table "${data.name}" in database ${databaseId}`, data)
+      const response = await this.http.post<Table>(`/database/tables/database/${databaseId}/`, data)
+
+      // Limpiar contenido por defecto de Baserow si es necesario
+      if (!data.data?.length && !data.skipDefaultCleanup) {
+        const cleanupStats = await this.ensureTableEmpty((response as any).id, data.name)
+        this.logDebug(`Table cleanup completed`, cleanupStats)
+      } else if (data.skipDefaultCleanup) {
+        this.logDebug(`Skipping default cleanup for table "${data.name}" as requested`)
+      }
+
+      this.logSuccess('create table', (response as any).id, { name: data.name })
+      return response
+    } catch (error) {
+      this.handleHttpError(error, 'create table', databaseId)
+    }
+  }
+
+  /**
+   * Crear nueva tabla (modo asíncrono)
+   *
+   * Crea una nueva tabla de forma asíncrona, ideal para archivos grandes
+   * o datasets extensos. Retorna un job_id para monitorear el progreso.
+   *
+   * @param databaseId - ID numérico de la database
+   * @param data - Configuración de la tabla (igual que createTable)
+   * @returns Promise con job_id para monitorear la creación
+   *
+   * @throws {BaserowValidationError} Si los datos son inválidos
+   *
+   * @example
+   * ```typescript
+   * // Crear tabla asíncrona para archivo CSV grande
+   * const job = await tableService.createAsync(123, {
+   *   name: 'Datos Masivos',
+   *   data: largeCsvData,
+   *   first_row_header: true
+   * })
+   *
+   * console.log(`Job iniciado: ${job.job_id}`)
+   * // Usar job_id para monitorear progreso
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async createAsync(databaseId: number, data: CreateTableRequest): Promise<{ job_id: string }> {
+    this.validationService.validateId(databaseId, 'database ID')
+    this.validationService.validateResourceName(data.name, 'table')
+
+    try {
+      this.logDebug(`Creating table async "${data.name}" in database ${databaseId}`, data)
+      const response = await this.http.post<{ job_id: string }>(
+        `/database/tables/database/${databaseId}/create-async/`,
+        data
+      )
+
+      // NOTA: createAsync no puede usar ensureTableEmpty() porque retorna job_id, no table_id
+      // El usuario debe verificar el estado del job y limpiar la tabla manualmente si es necesario
+
+      this.logSuccess('create table async', `job_${response.job_id}`, { name: data.name })
+      return response
+    } catch (error) {
+      this.handleHttpError(error, 'create table async', databaseId)
+    }
+  }
+
+  /**
+   * Actualizar tabla existente (método interno)
+   * @private - Solo para uso por TableContext
+   */
+  private async updateTableInternal(tableId: number, data: UpdateTableRequest): Promise<Table> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    if (data.name !== undefined) {
+      this.validationService.validateResourceName(data.name, 'table')
+    }
+
+    try {
+      this.logDebug(`Updating table ${tableId}`, data)
+      const response = await this.http.patch<Table>(`/database/tables/${tableId}/`, data)
+      this.logSuccess('update table', tableId)
+      return response
+    } catch (error) {
+      if ((error as any).status === 404) {
+        throw new BaserowNotFoundError('Table', tableId)
+      }
+      this.handleHttpError(error, 'update table', tableId)
+    }
+  }
+
+  /**
+   * Eliminar tabla (método interno)
+   * @private - Solo para uso por TableContext
+   */
+  private async deleteTableInternal(tableId: number): Promise<void> {
+    this.validationService.validateId(tableId, 'table ID')
+    return this.deleteById('/database/tables', tableId)
+  }
+
+  /**
+   * Verificar si una tabla existe
+   *
+   * Verifica la existencia de una tabla sin cargar todos sus metadatos.
+   * Útil para validaciones antes de operaciones.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @returns Promise que resuelve a true si existe, false si no
+   *
+   * @example
+   * ```typescript
+   * const exists = await tableService.exists(456)
+   * if (exists) {
+   *   console.log('La tabla existe')
+   * } else {
+   *   console.log('La tabla no existe')
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async exists(tableId: number): Promise<boolean> {
+    try {
+      await this.get(tableId)
+      return true
+    } catch (error) {
+      if (error instanceof BaserowNotFoundError) {
+        return false
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Obtener esquema completo de una tabla
+   *
+   * Recupera el esquema completo de una tabla incluyendo sus metadatos
+   * y todos los campos con sus definiciones. Útil para análisis de estructura.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @returns Promise con esquema completo (tabla + campos)
+   *
+   * @throws {BaserowValidationError} Si el tableId es inválido
+   *
+   * @example
+   * ```typescript
+   * const schema = await tableService.getSchema(456)
+   * console.log(`Tabla: ${schema.table.name}`)
+   * console.log(`Campos: ${schema.fields.length}`)
+   * schema.fields.forEach(field => {
+   *   console.log(`- ${field.name} (${field.type})`)
+   * })
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async getSchema(tableId: number): Promise<{
+    table: Table
+    fields: Field[]
+  }> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    try {
+      this.logDebug(`Fetching schema for table ${tableId}`)
+      const [table, fieldsResponse] = await Promise.all([
+        this.get(tableId),
+        this.http.get<BaserowResponse<Field>>(`/database/fields/`, {
+          params: { table_id: tableId }
+        })
+      ])
+
+      this.logSuccess('get table schema', tableId, { fieldCount: fieldsResponse.results.length })
+      return {
+        table,
+        fields: fieldsResponse.results
+      }
+    } catch (error) {
+      this.handleHttpError(error, 'get table schema', tableId)
+    }
+  }
+
+  /**
+   * Duplicar tabla
+   *
+   * Crea una copia exacta de una tabla existente incluyendo estructura
+   * y datos. Opcionalmente permite especificar un nuevo nombre.
+   *
+   * @param tableId - ID numérico de la tabla a duplicar
+   * @param newName - Nombre para la tabla duplicada (opcional)
+   * @returns Promise con la tabla duplicada
+   *
+   * @throws {BaserowValidationError} Si los parámetros son inválidos
+   *
+   * @example
+   * ```typescript
+   * const duplicated = await tableService.duplicate(456, 'Copia de Usuarios')
+   * console.log(`Tabla duplicada: ${duplicated.id}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async duplicate(tableId: number, newName?: string): Promise<Table> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    const originalTable = await this.get(tableId)
+    const name = newName || `${originalTable.name} (copy)`
+
+    if (newName) {
+      this.validationService.validateResourceName(newName, 'table')
+    }
+
+    try {
+      this.logDebug(`Duplicating table ${tableId} with name "${name}"`, { originalName: originalTable.name })
+      const response = await this.http.post<Table>(`/database/tables/${tableId}/duplicate/`, { name })
+      this.logSuccess('duplicate table', (response as any).id, { originalId: tableId, newName: name })
+      return response
+    } catch (error) {
+      this.handleHttpError(error, 'duplicate table', tableId)
+    }
+  }
+
+  /**
+   * Reordenar tabla en la database
+   *
+   * Cambia la posición de una tabla en el orden de visualización
+   * dentro de la database. Permite especificar posición relativa.
+   *
+   * @param tableId - ID numérico de la tabla a reordenar
+   * @param beforeId - ID de tabla antes de la cual colocar (opcional)
+   * @returns Promise con la tabla reordenada
+   *
+   * @throws {BaserowNotFoundError} Si alguna tabla no existe
+   * @throws {BaserowValidationError} Si los IDs son inválidos
+   *
+   * @example
+   * ```typescript
+   * // Mover tabla al final
+   * await tableService.reorder(456)
+   *
+   * // Mover tabla antes de otra específica
+   * await tableService.reorder(456, 123)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async reorder(tableId: number, beforeId?: number): Promise<Table> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    const data: any = {}
+    if (beforeId !== undefined) {
+      this.validationService.validateId(beforeId, 'before table ID')
+      data.before_id = beforeId
+    }
+
+    try {
+      this.logDebug(`Reordering table ${tableId}`, data)
+      const response = await this.http.patch<Table>(`/database/tables/${tableId}/move/`, data)
+      this.logSuccess('reorder table', tableId)
+      return response
+    } catch (error) {
+      if ((error as any).status === 404) {
+        throw new BaserowNotFoundError('Table', tableId)
+      }
+      this.handleHttpError(error, 'reorder table', tableId)
+    }
+  }
+
+  /**
+   * Obtener estadísticas de una tabla
+   *
+   * Recopila información estadística sobre una tabla incluyendo
+   * número de campos y filas. Útil para dashboards y monitoreo.
+   *
+   * @param tableId - ID numérico de la tabla
+   * @returns Promise con estadísticas de la tabla
+   *
+   * @throws {BaserowValidationError} Si el tableId es inválido
+   *
+   * @example
+   * ```typescript
+   * const stats = await tableService.getStats(456)
+   * console.log(`Campos: ${stats.fieldCount}`)
+   * console.log(`Filas: ${stats.rowCount}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async getStats(tableId: number): Promise<{
+    fieldCount: number
+    rowCount: number
+  }> {
+    this.validationService.validateId(tableId, 'table ID')
+
+    try {
+      this.logDebug(`Fetching stats for table ${tableId}`)
+      const [schema, rowCountResponse] = await Promise.all([
+        this.getSchema(tableId),
+        this.http.get<BaserowResponse<any>>(`/database/rows/table/${tableId}/`, { params: { size: 1 } })
+      ])
+
+      const stats = {
+        fieldCount: schema.fields.length,
+        rowCount: rowCountResponse.count
+      }
+
+      this.logSuccess('get table stats', tableId, stats)
+      return stats
+    } catch (error) {
+      this.handleHttpError(error, 'get table stats', tableId)
+    }
+  }
+
+  /**
+   * Asegurar que una tabla esté completamente vacía (sin campos ni filas)
+   *
+   * **Contexto**: Baserow automáticamente crea campos y filas de ejemplo cuando
+   * se crea una tabla sin datos iniciales. Este método limpia ese contenido
+   * para garantizar tablas mínimas (solo campo primario).
+   *
+   * **Proceso de limpieza**:
+   * 1. Obtiene todos los campos de la tabla
+   * 2. Elimina campos secundarios (preserva campo primario obligatorio)
+   * 3. Verifica que no queden filas residuales
+   * 4. Registra estadísticas de limpieza
+   *
+   * **Limitación de Baserow**: El campo primario NO se puede eliminar
+   * (ERROR_CANNOT_DELETE_PRIMARY_FIELD), por lo que las tablas "vacías"
+   * siempre tendrán al menos 1 campo primario.
+   *
+   * @param tableId - ID de la tabla a limpiar
+   * @param tableName - Nombre de la tabla (para logging)
+   * @returns Promise que resuelve cuando la limpieza está completa
+   *
+   * @private
+   * @since 1.0.0
+   */
+  private async ensureTableEmpty(
+    tableId: number,
+    tableName: string
+  ): Promise<{
+    wasAlreadyEmpty: boolean
+    removedFields: number
+    finalRowCount: number
+    cleanupErrors: number
+  }> {
+    const stats = {
+      wasAlreadyEmpty: false,
+      removedFields: 0,
+      finalRowCount: 0,
+      cleanupErrors: 0
+    }
+
+    try {
+      this.logDebug(`[BASEROW CLEANUP] Ensuring table "${tableName}" (ID: ${tableId}) is empty`)
+
+      // 1. Verificar y limpiar campos por defecto de Baserow
+      const fieldsResponse = await this.http.get<BaserowResponse<Field> | Field[]>(`/database/fields/table/${tableId}/`)
+      const fields = Array.isArray(fieldsResponse) ? fieldsResponse : fieldsResponse.results || []
+
+      stats.removedFields = fields.length
+
+      if (fields.length <= 1 && fields.every(f => f.primary)) {
+        stats.wasAlreadyEmpty = true
+        this.logDebug(`[BASEROW CLEANUP] Table "${tableName}" only has primary field (no extra default fields created)`)
+      } else {
+        this.logger?.info(
+          `[BASEROW CLEANUP] Table "${tableName}" created with ${fields.length} default fields by Baserow - removing them`,
+          {
+            tableId,
+            fieldNames: fields.map(f => f.name),
+            fieldTypes: fields.map(f => f.type)
+          }
+        )
+
+        // Eliminar todos los campos EXCEPTO el campo primario
+        // Baserow no permite eliminar el campo primario (ERROR_CANNOT_DELETE_PRIMARY_FIELD)
+        const nonPrimaryFields = fields.filter(field => !field.primary)
+        const primaryFields = fields.filter(field => field.primary)
+
+        this.logger?.info(
+          `[BASEROW CLEANUP] Found ${fields.length} fields: ${primaryFields.length} primary, ${nonPrimaryFields.length} secondary`,
+          {
+            primaryFields: primaryFields.map(f => ({ name: f.name, id: f.id, type: f.type })),
+            secondaryFields: nonPrimaryFields.map(f => ({ name: f.name, id: f.id, type: f.type }))
+          }
+        )
+
+        // Solo eliminar campos no-primarios
+        for (const field of nonPrimaryFields) {
+          try {
+            await this.http.delete(`/database/fields/${field.id}/`)
+            this.logDebug(
+              `[BASEROW CLEANUP] Removed secondary field "${field.name}" (type: ${field.type}, ID: ${field.id})`
+            )
+          } catch (deleteError) {
+            stats.cleanupErrors++
+            this.logger?.error(`[BASEROW CLEANUP] Failed to remove field "${field.name}" from table "${tableName}":`, {
+              fieldId: field.id,
+              fieldType: field.type,
+              error: deleteError
+            })
+          }
+        }
+
+        // Actualizar stats para reflejar solo campos eliminables
+        stats.removedFields = nonPrimaryFields.length
+      }
+
+      // 2. Limpiar filas por defecto que crea Baserow
+      const rowsResponse = await this.http.get<BaserowResponse<any>>(`/database/rows/table/${tableId}/`, {
+        params: { size: 100 } // Obtener hasta 100 filas para eliminar
+      })
+
+      if (rowsResponse.count > 0) {
+        this.logger?.info(
+          `[BASEROW CLEANUP] Table "${tableName}" has ${rowsResponse.count} default rows - removing them`,
+          {
+            tableId,
+            rowIds: rowsResponse.results?.slice(0, 5).map((r: any) => r.id) || []
+          }
+        )
+
+        // Eliminar todas las filas por defecto
+        const allRows = rowsResponse.results || []
+        for (const row of allRows) {
+          try {
+            await this.http.delete(`/database/rows/table/${tableId}/${row.id}/`)
+            this.logDebug(`[BASEROW CLEANUP] Removed default row ID ${row.id} from table "${tableName}"`)
+          } catch (deleteError) {
+            stats.cleanupErrors++
+            this.logger?.error(`[BASEROW CLEANUP] Failed to remove row ${row.id} from table "${tableName}":`, {
+              rowId: row.id,
+              error: deleteError
+            })
+          }
+        }
+
+        // Verificar estado final después de limpiar filas
+        const finalRowsResponse = await this.http.get<BaserowResponse<any>>(`/database/rows/table/${tableId}/`, {
+          params: { size: 1 }
+        })
+        stats.finalRowCount = finalRowsResponse.count
+      } else {
+        stats.finalRowCount = 0
+      }
+
+      // 3. Log resultado final
+      const resultLevel = stats.cleanupErrors > 0 ? 'warn' : 'info'
+      const message = stats.wasAlreadyEmpty
+        ? `[BASEROW CLEANUP] Table "${tableName}" only had primary field`
+        : `[BASEROW CLEANUP] Successfully cleaned table "${tableName}" (primary field preserved)`
+
+      this.logger?.[resultLevel]?.(message, {
+        tableId,
+        tableName,
+        wasAlreadyEmpty: stats.wasAlreadyEmpty,
+        removedFields: stats.removedFields,
+        finalRowCount: stats.finalRowCount,
+        cleanupErrors: stats.cleanupErrors,
+        summary: `Removed ${stats.removedFields} fields, ${stats.finalRowCount} rows remaining, ${stats.cleanupErrors} errors`
+      })
+
+      this.logSuccess('ensured table empty', tableId, stats)
+      return stats
+    } catch (error) {
+      // Log error pero no fallar la creación de la tabla
+      this.logger?.error(`[BASEROW CLEANUP] Failed to verify/clean table "${tableName}":`, {
+        tableId,
+        tableName,
+        error: error,
+        note: 'Table creation succeeded but cleanup failed'
+      })
+
+      return {
+        ...stats,
+        cleanupErrors: stats.cleanupErrors + 1
+      }
+    }
+  }
+
+  /**
+   * Listar todas las tablas accesibles con Database Token
+   *
+   * Endpoint específico para Database Tokens que devuelve todas las tablas
+   * a las que el token tiene acceso, sin necesidad de especificar database.
+   *
+   * @returns Promise con array de tablas con información básica
+   * @throws {BaserowError} Si hay error de red o el token no es válido
+   *
+   * @example
+   * ```typescript
+   * const tables = await tableService.findAllTablesWithToken()
+   * console.log(`Token tiene acceso a ${tables.length} tablas`)
+   * tables.forEach(table => {
+   *   console.log(`Tabla: ${table.name} (DB: ${table.database_id})`)
+   * })
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async findAllTablesWithToken(): Promise<TableFromAllTables[]> {
+    try {
+      this.logDebug('Fetching all tables accessible with database token')
+      const response = await this.http.get<TableFromAllTables[]>('/database/tables/all-tables/')
+
+      // La respuesta es directamente un array de tablas
+      const tables = Array.isArray(response) ? response : []
+
+      this.logSuccess('fetch all tables with token', undefined, { count: tables.length })
+      return tables
+    } catch (error) {
+      this.handleHttpError(error, 'fetch all tables with token')
+    }
+  }
+
+  // ===== FRIEND ACCESS PATTERN FOR TABLE CONTEXT =====
+  // Symbol-based access que no aparece en la API pública pero permite acceso interno
+
+  /**
+   * Friend access para TableContext
+   * No aparece en intellisense normal ni en la API pública
+   * @internal
+   */
+  get [Symbol.for('tableContext')]() {
+    return {
+      createTable: this.createTableInternal.bind(this),
+      updateTable: this.updateTableInternal.bind(this),
+      deleteTable: this.deleteTableInternal.bind(this)
+    }
+  }
+}