@gzl10/baserow 1.2.0

package/src/express/serializers.ts

@@ -0,0 +1,314 @@
+/**
+ * Serializadores Express para @gzl10/baserow
+ *
+ * Utilidades para convertir objetos de Baserow en formatos apropiados para respuestas Express.
+ * Proporciona serialización consistente y limpieza de datos para APIs REST.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express'
+ * import { BaserowClient, express as baserowExpress } from '@gzl10/baserow'
+ *
+ * app.get('/api/tables/:id/rows', async (req, res, next) => {
+ *   try {
+ *     const result = await req.baserow!.database(123).table(456).rows.list()
+ *     const serialized = baserowExpress.serializePaginated(result)
+ *     res.json(serialized)
+ *   } catch (error) {
+ *     next(error) // Will be handled by baserowExpress.errorHandler()
+ *   }
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ */
+
+import type { Row, Table, Field, Database, Workspace, QueryOptions } from '../types'
+
+// Definir tipos locales para los serializers Express
+export interface PaginatedResult<T> {
+  results: T[]
+  count: number
+  next: string | null
+  previous: string | null
+}
+
+/**
+ * Formato estándar para respuestas paginadas
+ */
+export interface PaginatedResponse<T = any> {
+  data: T[]
+  pagination: {
+    count: number
+    next: string | null
+    previous: string | null
+    page: number
+    totalPages: number
+  }
+  meta?: {
+    total: number
+    filters?: Record<string, any>
+    ordering?: string
+  }
+}
+
+/**
+ * Formato para respuestas de filas con metadatos
+ */
+export interface RowsResponse {
+  data: Row[]
+  fields: Field[]
+  table: {
+    id: number
+    name: string
+    database_id: number
+  }
+  pagination?: PaginatedResponse<Row>['pagination']
+}
+
+/**
+ * Serializa resultado paginado de Baserow para respuesta Express
+ *
+ * Convierte el formato interno de paginación de Baserow en un formato
+ * estándar y consistente para APIs REST.
+ *
+ * @param result - Resultado paginado de Baserow
+ * @param options - Opciones adicionales de serialización
+ * @returns Respuesta paginada formateada
+ *
+ * @example
+ * ```typescript
+ * import { express as baserowExpress } from '@gzl10/baserow'
+ *
+ * app.get('/api/rows', async (req, res) => {
+ *   const result = await req.baserow!.database(123).table(456).rows.list()
+ *   const response = baserowExpress.serializePaginated(result, {
+ *     baseUrl: req.baseUrl,
+ *     includeTotal: true
+ *   })
+ *   res.json(response)
+ * })
+ * ```
+ */
+export function serializePaginated<T>(
+  result: PaginatedResult<T>,
+  options: {
+    baseUrl?: string
+    includeTotal?: boolean
+  } = {}
+): PaginatedResponse<T> {
+  const { baseUrl = '', includeTotal = true } = options
+
+  // Calcular página actual y total de páginas
+  const page = Math.floor((result.previous ? extractPageFromUrl(result.previous) : 0) + 1)
+  const totalPages = result.count > 0 ? Math.ceil(result.count / result.results.length) : 1
+
+  const response: PaginatedResponse<T> = {
+    data: result.results,
+    pagination: {
+      count: result.results.length,
+      next: result.next ? makeRelativeUrl(result.next, baseUrl) : null,
+      previous: result.previous ? makeRelativeUrl(result.previous, baseUrl) : null,
+      page,
+      totalPages
+    }
+  }
+
+  if (includeTotal) {
+    response.meta = {
+      total: result.count
+    }
+  }
+
+  return response
+}
+
+/**
+ * Serializa filas de tabla con metadatos completos
+ *
+ * Incluye datos de filas junto con información de campos y tabla
+ * para proporcionar contexto completo en la respuesta.
+ *
+ * @param rows - Filas de la tabla
+ * @param table - Información de la tabla
+ * @param fields - Campos de la tabla
+ * @returns Respuesta completa con filas y metadatos
+ */
+export function serializeRowsWithMeta(rows: Row[] | PaginatedResult<Row>, table: Table, fields: Field[]): RowsResponse {
+  const isPaginated = 'results' in rows
+  const rowData = isPaginated ? rows.results : rows
+
+  const response: RowsResponse = {
+    data: rowData,
+    fields: fields,
+    table: {
+      id: table.id,
+      name: table.name,
+      database_id: table.database_id
+    }
+  }
+
+  if (isPaginated) {
+    response.pagination = serializePaginated(rows).pagination
+  }
+
+  return response
+}
+
+/**
+ * Limpia y serializa un campo de Baserow
+ *
+ * Remueve propiedades internas y normaliza la estructura del campo
+ * para respuestas de API.
+ *
+ * @param field - Campo de Baserow a limpiar
+ * @returns Campo serializado
+ */
+export function cleanField(field: Field): Partial<Field> {
+  // Propiedades core que siempre incluir
+  const cleaned: Partial<Field> = {
+    id: field.id,
+    name: field.name,
+    type: field.type,
+    order: field.order,
+    primary: field.primary
+  }
+
+  // Agregar propiedades específicas del tipo si existen
+  if ('table_id' in field) cleaned.table_id = field.table_id
+  if ('description' in field) cleaned.description = field.description
+  if ('read_only' in field) cleaned.read_only = field.read_only
+
+  // Propiedades específicas de tipos de campo
+  if ('number_decimal_places' in field) cleaned.number_decimal_places = field.number_decimal_places
+  if ('date_format' in field) cleaned.date_format = field.date_format
+  if ('date_include_time' in field) cleaned.date_include_time = field.date_include_time
+  if ('select_options' in field) cleaned.select_options = field.select_options
+  if ('link_row_table_id' in field) cleaned.link_row_table_id = field.link_row_table_id
+
+  return cleaned
+}
+
+/**
+ * Serializa tabla de Baserow para respuesta Express
+ *
+ * @param table - Tabla de Baserow
+ * @param includeFields - Si incluir campos en la respuesta
+ * @returns Tabla serializada
+ */
+export function serializeTable(table: Table, includeFields = false): Partial<Table> {
+  const serialized: Partial<Table> = {
+    id: table.id,
+    name: table.name,
+    order: table.order,
+    database_id: table.database_id
+  }
+
+  if (includeFields && 'fields' in table && table.fields) {
+    ;(serialized as any).fields = table.fields
+  }
+
+  return serialized
+}
+
+/**
+ * Serializa database de Baserow para respuesta Express
+ *
+ * @param database - Database de Baserow
+ * @param includeTables - Si incluir tablas en la respuesta
+ * @returns Database serializada
+ */
+export function serializeDatabase(database: Database, includeTables = false): Partial<Database> {
+  const serialized: Partial<Database> = {
+    id: database.id,
+    name: database.name,
+    order: database.order,
+    workspace: database.workspace
+      ? {
+          id: database.workspace.id,
+          name: database.workspace.name
+        }
+      : undefined
+  }
+
+  if (includeTables && database.tables) {
+    serialized.tables = database.tables
+  }
+
+  return serialized
+}
+
+/**
+ * Serializa workspace de Baserow para respuesta Express
+ *
+ * @param workspace - Workspace de Baserow
+ * @returns Workspace serializado
+ */
+export function serializeWorkspace(workspace: Workspace): Partial<Workspace> {
+  return {
+    id: workspace.id,
+    name: workspace.name,
+    order: workspace.order
+  }
+}
+
+/**
+ * Crea respuesta de éxito estándar
+ *
+ * @param data - Datos a incluir en la respuesta
+ * @param message - Mensaje opcional de éxito
+ * @returns Respuesta estándar de éxito
+ */
+export function createSuccessResponse<T>(data: T, message?: string) {
+  return {
+    success: true,
+    data,
+    message,
+    timestamp: new Date().toISOString()
+  }
+}
+
+/**
+ * Serializa opciones de query para logging o debugging
+ *
+ * @param options - Opciones de query de Baserow
+ * @returns Opciones limpias para logging
+ */
+export function serializeQueryOptions(options: QueryOptions): Record<string, any> {
+  const cleaned: Record<string, any> = {}
+
+  if (options.page !== undefined) cleaned.page = options.page
+  if (options.size !== undefined) cleaned.size = options.size
+  if (options.search) cleaned.search = options.search
+  if (options.order_by) cleaned.order_by = options.order_by
+  if (options.user_field_names !== undefined) cleaned.user_field_names = options.user_field_names
+  if (options.filters) cleaned.filters = options.filters
+
+  return cleaned
+}
+
+// Utilidades internas
+
+/**
+ * Extrae número de página de URL de paginación
+ */
+function extractPageFromUrl(url: string): number {
+  const match = url.match(/[?&]page=(\d+)/)
+  return match ? parseInt(match[1], 10) : 1
+}
+
+/**
+ * Convierte URL absoluta a relativa
+ */
+function makeRelativeUrl(absoluteUrl: string, baseUrl: string): string {
+  if (!baseUrl || !absoluteUrl.startsWith('http')) {
+    return absoluteUrl
+  }
+
+  try {
+    const url = new URL(absoluteUrl)
+    return url.pathname + url.search
+  } catch {
+    return absoluteUrl
+  }
+}

package/src/index.ts

@@ -0,0 +1,247 @@
+/**
+ * @gzl10/baserow - Cliente TypeScript avanzado para Baserow API v1.35+ (2025)
+ *
+ * Cliente moderno con arquitectura de 3 clientes especializados, PrismaBaserowMapper
+ * para sintaxis familiar, y cobertura completa de 21/22 tipos de campos.
+ *
+ * **Características principales:**
+ * - 🎯 **Arquitectura de 3 Clientes**: Token, Admin Global y Admin Workspace
+ * - 🗺️ **PrismaBaserowMapper**: Sintaxis familiar estilo Prisma con 35+ tests
+ * - 📋 **21/22 Tipos de Campos**: Cobertura prácticamente completa
+ * - 🚀 **HTTP Optimizado**: 36% menos código con axios-retry + axios-rate-limit
+ * - ⚡ **Operaciones Bulk**: Procesamiento optimizado con retry logic
+ * - 🧪 **Testing Robusto**: 35+ tests de integración + tests del mapper
+ *
+ * ---
+ *
+ * ## 🤖 Guía para IA: ¿Qué Cliente Usar?
+ *
+ * ### 1️⃣ ClientWithToken (Database Token)
+ * **✅ Usar cuando:**
+ * - Solo necesitas **leer/escribir datos** (CRUD de filas)
+ * - Aplicación cliente (frontend, mobile, edge functions)
+ * - Scope limitado a tablas específicas predefinidas
+ * - No necesitas crear/modificar estructura (tablas, campos, workspaces)
+ * - Máxima seguridad (token con permisos granulares)
+ *
+ * **❌ NO usar cuando:**
+ * - Necesitas crear/modificar tablas o campos
+ * - Necesitas gestionar workspaces
+ * - Necesitas operaciones administrativas
+ *
+ * **Performance:** ⚡⚡⚡ (Sin overhead de JWT, conexión directa)
+ *
+ * ### 2️⃣ ClientWithCreds (JWT Global - Multi-Workspace)
+ * **✅ Usar cuando:**
+ * - Administración de **múltiples workspaces**
+ * - Scripts de migración completa entre entornos
+ * - Panel de control administrativo multi-tenant
+ * - Necesitas API jerárquica: `admin.workspace('X').database('Y').create()`
+ * - Operaciones de setup inicial o teardown completo
+ *
+ * **❌ NO usar cuando:**
+ * - Solo trabajas con un workspace específico (usa ClientWithCredsWs)
+ * - Solo necesitas datos sin admin (usa ClientWithToken)
+ * - Aplicación cliente con scope limitado
+ *
+ * **Performance:** ⚡⚡ (Overhead de JWT + validación multi-workspace)
+ *
+ * ### 3️⃣ ClientWithCredsWs (JWT Workspace - Single Workspace)
+ * **✅ Usar cuando:**
+ * - Administración de **un workspace específico**
+ * - API simplificada sin prefijo workspace en cada llamada
+ * - Aplicación empresarial con scope de empresa/proyecto único
+ * - Necesitas admin pero scope está bien definido
+ * - Mejor DX que ClientWithCreds para casos single-workspace
+ *
+ * **❌ NO usar cuando:**
+ * - Necesitas acceso a múltiples workspaces
+ * - Solo necesitas datos sin admin (usa ClientWithToken)
+ *
+ * **Performance:** ⚡⚡ (Overhead de JWT pero scope optimizado)
+ *
+ * ---
+ *
+ * ## 📊 Tabla Comparativa de Capacidades
+ *
+ * | Capability              | Token | CredsGlobal | CredsWs |
+ * |-------------------------|-------|-------------|---------|
+ * | Read/Write Data (CRUD)  | ✅    | ✅          | ✅      |
+ * | Create/Modify Tables    | ❌    | ✅          | ✅      |
+ * | Create/Modify Fields    | ❌    | ✅          | ✅      |
+ * | Manage Workspaces       | ❌    | ✅          | ❌      |
+ * | Multi-Workspace Access  | ❌    | ✅          | ❌      |
+ * | Auto-Refresh JWT        | ❌    | ✅          | ✅      |
+ * | Needs User Credentials  | ❌    | ✅          | ✅      |
+ * | Hierarchical API        | ❌    | ✅          | ✅      |
+ * | Granular Permissions    | ✅    | ❌          | ❌      |
+ * | Performance             | ⚡⚡⚡  | ⚡⚡         | ⚡⚡     |
+ * | Security (Least Priv)   | ⚡⚡⚡  | ⚡          | ⚡⚡     |
+ *
+ * ---
+ *
+ * ## 🎯 Árbol de Decisión Rápido
+ *
+ * ```
+ * ¿Necesitas operaciones admin (crear tablas/campos/workspaces)?
+ *   │
+ *   ├─ NO  → ClientWithToken (Database Token)
+ *   │         └─ Máxima seguridad, solo datos
+ *   │
+ *   └─ SÍ  → ¿Múltiples workspaces?
+ *             │
+ *             ├─ SÍ → ClientWithCreds (JWT Global)
+ *             │        └─ API: admin.workspace('X').database('Y')
+ *             │
+ *             └─ NO  → ClientWithCredsWs (JWT Workspace)
+ *                      └─ API: admin.database('Y') (sin prefijo workspace)
+ * ```
+ *
+ * ---
+ *
+ * @example
+ * ```typescript
+ * import { BaserowClient, PrismaBaserowMapper } from '@gzl10/baserow'
+ * // Importar tipos de configuración con aliases descriptivos
+ * import type { TokenConfig, CredentialsConfig, CredentialsWorkspaceConfig } from '@gzl10/baserow'
+ * // Importar clases de cliente para tipado avanzado
+ * import type { ClientWithToken, ClientWithCreds, ClientWithCredsWs } from '@gzl10/baserow'
+ *
+ * // === PRISMA MAPPER - CARACTERÍSTICA PRINCIPAL ===
+ * const client = await BaserowClient.create({ url, token })
+ *
+ * // Sintaxis Prisma familiar
+ * 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 }
+ * }
+ *
+ * // Transformación automática a Baserow API
+ * const baserowOptions = PrismaBaserowMapper.transformPrismaToBaserow(prismaQuery)
+ * const rows = await client.database(123).table(456).rows.list(baserowOptions)
+ *
+ * // === ARQUITECTURA DE 3 CLIENTES ===
+ *
+ * // 1. Cliente con Database Token (solo datos)
+ * const tokenConfig: TokenConfig = {
+ *   url: 'https://baserow.example.com',
+ *   token: process.env.BASEROW_DB_TOKEN!
+ * }
+ * const client = await BaserowClient.create(tokenConfig)
+ * const rows = await client.database(123).table(456).rows.list()
+ *
+ * // 2. Cliente Admin Global (multi-workspace)
+ * const adminConfig: CredentialsConfig = {
+ *   url: 'https://baserow.example.com',
+ *   credentials: { email: 'admin@example.com', password: 'password' }
+ * }
+ * const admin = await BaserowClient.create(adminConfig)
+ * const workspaces = await admin.workspaces.list()
+ * const database = await admin.workspace('Company').databases.create('CRM')
+ *
+ * // 3. Cliente Admin Workspace (scope específico)
+ * const adminWSConfig: CredentialsWorkspaceConfig = {
+ *   url: 'https://baserow.example.com',
+ *   credentials: { email: 'admin@example.com', password: 'password' },
+ *   workspace: 'Company'
+ * }
+ * const adminWS = await BaserowClient.create(adminWSConfig)
+ * const databases = await adminWS.databases.list()
+ * const table = await adminWS.database('CRM').tables.create({ name: 'Customers' })
+ *
+ * // === COBERTURA COMPLETA DE CAMPOS ===
+ * // 21/22 tipos de campos soportados incluyendo campos avanzados
+ * const textField = await table.field.createText('full_name')
+ * 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!
+ *
+ * // === CONFIGURACIONES DE PERFORMANCE ===
+ * import { PERFORMANCE_PRESETS } from '@gzl10/baserow'
+ *
+ * const prodClient = await BaserowClient.create({
+ *   url: 'https://baserow.example.com',
+ *   token: process.env.TOKEN,
+ *   performance: PERFORMANCE_PRESETS.production  // Balanceado: 30s timeout, 3 retries, 10 req/s
+ * })
+ *
+ * // === UTILIDADES EXPRESS OPCIONALES ===
+ * import express from 'express'
+ * import { express as baserowExpress } from '@gzl10/baserow'
+ *
+ * const app = express()
+ * app.use('/api', baserowExpress.baserowContext(client))
+ * app.use(baserowExpress.errorHandler())
+ * ```
+ *
+ * @version 1.1.0+
+ * @since 2025
+ */
+
+// Cliente principal unificado
+export { BaserowClient } from './BaserowClient'
+
+// Clases de cliente especializadas (para tipado avanzado)
+export { ClientWithToken } from './ClientWithToken'
+export { ClientWithCreds } from './ClientWithCreds'
+export { ClientWithCredsWs } from './ClientWithCredsWs'
+
+// Tipos esenciales para el usuario
+export type {
+  BaserowTokenConfig,
+  BaserowCredentialsConfig,
+  BaserowCredentialsWorkspaceConfig,
+  BaserowUnifiedConfig,
+  BaserowCredentials,
+  BaserowPerformanceOptions,
+  Workspace,
+  Database,
+  Table,
+  Field,
+  FieldType,
+  Row,
+  QueryOptions,
+  PrismaLikeQueryOptions,
+  FieldOperators,
+  WhereClause,
+  OrderByClause,
+  SelectClause,
+  DatabaseToken,
+  DatabaseSchema,
+  TableSchema,
+  FieldSchema,
+  RelationshipSchema,
+  LoadSchemaOptions,
+  LoadSchemaResult,
+  SchemaControl
+} from './types'
+
+// Aliases descriptivos de configuración (DX-friendly)
+export type { TokenConfig, CredentialsConfig, CredentialsWorkspaceConfig } from './types'
+
+// Contextos para tipado avanzado (solo tipos, no instanciables directamente)
+export type { DatabaseContext } from './contexts/DatabaseContext'
+export type { TableContext } from './contexts/TableContext'
+export type { WorkspaceContext } from './contexts/WorkspaceContext'
+
+// Errores que puede capturar el usuario
+export { BaserowError, BaserowValidationError, BaserowNotFoundError, BaserowRateLimitError } from './types'
+
+// Configuraciones de performance predefinidas
+export { PERFORMANCE_PRESETS, getPerformancePreset } from './presets/performance'
+export type { PerformancePresetKey } from './presets/performance'
+
+// Utilidades Prisma Mapper
+export { PrismaBaserowMapper } from './utils/prisma-mapper'
+
+// Utilidades Express opcionales (sin dependencias)
+export * as express from './express/index'