@gzl10/baserow 1.2.0

package/src/express/errors.ts

@@ -0,0 +1,260 @@
+/**
+ * Manejo de errores Express para @gzl10/baserow
+ *
+ * Convertidores y middlewares para transformar BaserowError en respuestas HTTP apropiadas.
+ * Proporciona mapeo automático de errores de Baserow a códigos de estado HTTP estándar.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express'
+ * import { BaserowClient, express as baserowExpress } from '@gzl10/baserow'
+ *
+ * const app = express()
+ *
+ * // Setup middlewares
+ * app.use('/api', baserowExpress.baserowAuth(config))
+ *
+ * // Routes
+ * app.get('/api/table/:id', async (req, res, next) => {
+ *   try {
+ *     const table = await req.baserow!.database(123).table(parseInt(req.params.id)).get()
+ *     res.json(baserowExpress.serializeTable(table))
+ *   } catch (error) {
+ *     next(error) // Será manejado por errorHandler()
+ *   }
+ * })
+ *
+ * // Error handler global (debe ir al final)
+ * app.use(baserowExpress.errorHandler())
+ * ```
+ *
+ * @since 1.0.0
+ */
+
+import { BaserowError, BaserowNotFoundError, BaserowValidationError, BaserowRateLimitError } from '../types'
+import type { ExpressRequest, ExpressResponse, ExpressNextFunction } from './middleware'
+
+/**
+ * Formato estándar para respuestas de error
+ */
+export interface ErrorResponse {
+  error: string
+  code: string
+  status: number
+  details?: any
+  timestamp?: string
+}
+
+/**
+ * Convierte BaserowError a código de estado HTTP apropiado
+ *
+ * Mapea los tipos de error específicos de Baserow a códigos HTTP estándar:
+ * - BaserowNotFoundError → 404
+ * - BaserowValidationError → 400
+ * - BaserowRateLimitError → 429
+ * - BaserowError (generic auth) → 401
+ * - Otros BaserowError → 500
+ *
+ * @param error - Error de Baserow a convertir
+ * @returns Código de estado HTTP apropiado
+ */
+export function getHttpStatusCode(error: BaserowError): number {
+  if (error instanceof BaserowNotFoundError) {
+    return 404
+  }
+
+  if (error instanceof BaserowValidationError) {
+    return 400
+  }
+
+  if (error instanceof BaserowRateLimitError) {
+    return 429
+  }
+
+  // Detectar errores de auth por status code o mensaje
+  if (error.status === 401 || error.message?.toLowerCase().includes('auth')) {
+    return 401
+  }
+
+  // Usar status del error si está disponible
+  if (error.status) {
+    return error.status
+  }
+
+  // Default para errores desconocidos
+  return 500
+}
+
+/**
+ * Convierte BaserowError a formato de respuesta Express estándar
+ *
+ * Crea un objeto de error normalizado que incluye toda la información relevante
+ * sin exponer detalles internos sensibles.
+ *
+ * @param error - Error de Baserow a serializar
+ * @returns Objeto de error serializado para respuesta HTTP
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someBaserowOperation()
+ * } catch (error) {
+ *   const response = serializeError(error as BaserowError)
+ *   res.status(response.status).json(response)
+ * }
+ * ```
+ */
+export function serializeError(error: BaserowError): ErrorResponse {
+  const status = getHttpStatusCode(error)
+
+  const response: ErrorResponse = {
+    error: error.message || 'Unknown Baserow error',
+    code: error.constructor.name.replace('Error', '').toUpperCase(),
+    status,
+    timestamp: new Date().toISOString()
+  }
+
+  // Agregar detalles específicos para ciertos tipos de error
+  if (error instanceof BaserowValidationError) {
+    response.details = {
+      fieldErrors: error.fieldErrors
+    }
+  }
+
+  if (error instanceof BaserowRateLimitError) {
+    response.details = {
+      retryAfter: error.retryAfter
+    }
+  }
+
+  if (error instanceof BaserowNotFoundError) {
+    response.details = {
+      message: error.message
+    }
+  }
+
+  return response
+}
+
+/**
+ * Convierte Error genérico a formato de respuesta Express
+ *
+ * Maneja errores que no son específicos de Baserow (por ejemplo, errores de red,
+ * errores de validación de entrada, etc.).
+ *
+ * @param error - Error genérico a serializar
+ * @returns Objeto de error serializado
+ */
+export function serializeGenericError(error: Error): ErrorResponse {
+  return {
+    error: error.message || 'Internal server error',
+    code: 'INTERNAL_ERROR',
+    status: 500,
+    timestamp: new Date().toISOString()
+  }
+}
+
+/**
+ * Middleware Express para manejo automático de errores Baserow
+ *
+ * Convierte automáticamente errores de Baserow en respuestas HTTP apropiadas.
+ * Debe ser usado como el último middleware de la aplicación.
+ *
+ * @param options - Opciones de configuración del error handler
+ * @returns Middleware Express para manejo de errores
+ *
+ * @example
+ * ```typescript
+ * import { express as baserowExpress } from '@gzl10/baserow'
+ *
+ * // Al final de la configuración de middlewares
+ * app.use(baserowExpress.errorHandler({
+ *   includeStack: process.env.NODE_ENV === 'development',
+ *   logger: console
+ * }))
+ *
+ * // Ejemplo de error personalizado en ruta
+ * app.get('/api/custom', async (req, res, next) => {
+ *   try {
+ *     // Operación que puede fallar
+ *     const data = await req.baserow!.database(999).table(123).rows.list()
+ *     res.json(data)
+ *   } catch (error) {
+ *     next(error) // Automáticamente convierte BaserowError a HTTP response
+ *   }
+ * })
+ * ```
+ */
+export function errorHandler(
+  options: {
+    includeStack?: boolean
+    logger?: { error: (message: any) => void }
+  } = {}
+) {
+  return (error: any, req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => {
+    // Si ya se envió la respuesta, pasar al error handler por defecto
+    if ((res as any).headersSent) {
+      return next(error)
+    }
+
+    let response: ErrorResponse
+
+    if (error instanceof BaserowError) {
+      response = serializeError(error)
+    } else if (error instanceof Error) {
+      response = serializeGenericError(error)
+    } else {
+      // Error desconocido
+      response = {
+        error: 'Unknown error occurred',
+        code: 'UNKNOWN_ERROR',
+        status: 500,
+        timestamp: new Date().toISOString()
+      }
+    }
+
+    // Agregar stack trace en desarrollo
+    if (options.includeStack && error instanceof Error) {
+      ;(response as any).stack = error.stack
+    }
+
+    // Log del error
+    if (options.logger) {
+      options.logger.error(
+        'Baserow API Error: ' +
+          JSON.stringify({
+            error: response,
+            url: (req as any).url,
+            method: (req as any).method,
+            stack: error instanceof Error ? error.stack : undefined
+          })
+      )
+    }
+
+    res.status(response.status).json(response)
+  }
+}
+
+/**
+ * Handler de errores simplificado para casos básicos
+ *
+ * Versión simplificada del error handler que solo maneja errores de Baserow
+ * sin opciones de configuración adicionales.
+ *
+ * @returns Middleware Express básico para errores
+ */
+export function simpleErrorHandler() {
+  return (error: any, _req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => {
+    if ((res as any).headersSent) {
+      return next(error)
+    }
+
+    if (error instanceof BaserowError) {
+      const response = serializeError(error)
+      return res.status(response.status).json(response)
+    }
+
+    // Para errores no-Baserow, pasar al siguiente handler
+    next(error)
+  }
+}

package/src/express/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Utilidades Express para @gzl10/baserow
+ *
+ * Colección de middlewares, error handlers y serializadores opcionales
+ * para facilitar la integración con Express sin crear dependencias directas.
+ *
+ * @example
+ * ```typescript
+ * import { BaserowClient, express } from '@gzl10/baserow'
+ *
+ * const client = new BaserowClient({ url, token })
+ * const app = express()
+ *
+ * // Setup middlewares
+ * app.use('/api', express.baserowContext(client))
+ * app.use('/api', express.requireAuth())
+ *
+ * // Routes
+ * app.get('/api/tables/:tableId/rows', async (req, res, next) => {
+ *   try {
+ *     const rows = await req.baserow!.database(123).table(456).rows.list()
+ *     res.json(express.serializePaginated(rows))
+ *   } catch (error) {
+ *     next(error)
+ *   }
+ * })
+ *
+ * // Error handling
+ * app.use(express.errorHandler())
+ * ```
+ *
+ * @since 1.0.0
+ */
+
+// Middlewares
+export {
+  baserowContext,
+  baserowAuth,
+  requireAuth,
+  baserowCleanup,
+  type ExpressRequest,
+  type ExpressResponse,
+  type ExpressNextFunction,
+  type ExpressMiddleware
+} from './middleware'
+
+// Error handling
+export {
+  errorHandler,
+  simpleErrorHandler,
+  serializeError,
+  serializeGenericError,
+  getHttpStatusCode,
+  type ErrorResponse
+} from './errors'
+
+// Serializadores
+export {
+  serializePaginated,
+  serializeRowsWithMeta,
+  serializeTable,
+  serializeDatabase,
+  serializeWorkspace,
+  cleanField,
+  createSuccessResponse,
+  serializeQueryOptions,
+  type PaginatedResponse,
+  type RowsResponse
+} from './serializers'

package/src/express/middleware.ts

@@ -0,0 +1,225 @@
+/**
+ * Middlewares Express opcionales para @gzl10/baserow
+ *
+ * Utilidades que facilitan la integración con Express sin crear dependencias directas.
+ * Los tipos Express son inferidos dinámicamente para evitar dependency en @types/express.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express'
+ * import { BaserowClient, express as baserowExpress } from '@gzl10/baserow'
+ *
+ * const app = express()
+ * const client = await BaserowClient.create({ url, token })
+ *
+ * // Attach client to request
+ * app.use('/api', baserowExpress.baserowContext(client))
+ *
+ * // Auto-create client per request with auth from headers
+ * app.use('/api', baserowExpress.baserowAuth({
+ *   url: process.env.BASEROW_URL!,
+ *   token: process.env.BASEROW_TOKEN!
+ * }))
+ *
+ * // Routes now have access to req.baserow
+ * app.get('/api/rows', async (req, res) => {
+ *   const rows = await req.baserow!.database(123).table(456).rows.list()
+ *   res.json(rows)
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ */
+
+import type { BaserowConfig } from '../types'
+import { ClientWithToken } from '../ClientWithToken'
+
+/**
+ * Tipos Express mínimos sin dependencias
+ */
+export interface ExpressRequest {
+  [key: string]: any
+  headers: { [key: string]: string | string[] | undefined }
+  baserow?: ClientWithToken
+}
+
+export interface ExpressResponse {
+  status(code: number): ExpressResponse
+  json(body: any): ExpressResponse
+  send(body?: any): ExpressResponse
+}
+
+export interface ExpressNextFunction {
+  (error?: any): void
+}
+
+export type ExpressMiddleware = (
+  req: ExpressRequest,
+  res: ExpressResponse,
+  next: ExpressNextFunction
+) => void | Promise<void>
+
+/**
+ * Middleware para attachar cliente Baserow al request
+ *
+ * Agrega el cliente a `req.baserow` para uso en routes subsecuentes.
+ * El cliente debe ser creado externamente y reutilizado.
+ *
+ * @param client - Cliente Baserow configurado
+ * @returns Middleware Express
+ *
+ * @example
+ * ```typescript
+ * import { BaserowClient, express as baserowExpress } from '@gzl10/baserow'
+ *
+ * const client = await BaserowClient.create({ url, token })
+ * app.use('/api', baserowExpress.baserowContext(client))
+ *
+ * // En las rutas
+ * app.get('/api/tables', async (req, res) => {
+ *   const tables = await req.baserow!.database(123).tables.findMany()
+ *   res.json(tables)
+ * })
+ * ```
+ */
+export function baserowContext(client: ClientWithToken): ExpressMiddleware {
+  return (req: ExpressRequest, _res: ExpressResponse, next: ExpressNextFunction) => {
+    req.baserow = client
+    next()
+  }
+}
+
+/**
+ * Middleware para auto-crear cliente Baserow por request
+ *
+ * Crea un nuevo cliente para cada request basado en la configuración.
+ * Útil cuando cada request puede tener diferentes tokens o configuraciones.
+ *
+ * @param config - Configuración base de Baserow
+ * @returns Middleware Express
+ *
+ * @example
+ * ```typescript
+ * import { express as baserowExpress } from '@gzl10/baserow'
+ *
+ * app.use('/api', baserowExpress.baserowAuth({
+ *   url: process.env.BASEROW_URL!,
+ *   token: process.env.BASEROW_TOKEN! // Puede ser sobrescrito por headers
+ * }))
+ *
+ * // Cliente auto-creado por request disponible en req.baserow
+ * app.get('/api/data', async (req, res) => {
+ *   const rows = await req.baserow!.database(123).table(456).rows.list()
+ *   res.json(rows)
+ * })
+ * ```
+ */
+export function baserowAuth(config: BaserowConfig): ExpressMiddleware {
+  return (req: ExpressRequest, _res: ExpressResponse, next: ExpressNextFunction) => {
+    try {
+      // Permitir override del token vía headers
+      const authHeader = req.headers.authorization as string
+      const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : config.token
+
+      const clientConfig: BaserowConfig = {
+        ...config,
+        token
+      }
+
+      req.baserow = new ClientWithToken(clientConfig)
+      next()
+    } catch (error) {
+      next(error)
+    }
+  }
+}
+
+/**
+ * Middleware para requerir autenticación Baserow
+ *
+ * Valida que existe un cliente Baserow válido en el request.
+ * Debe usarse después de `baserowContext` o `baserowAuth`.
+ *
+ * @returns Middleware Express
+ *
+ * @example
+ * ```typescript
+ * import { express as baserowExpress } from '@gzl10/baserow'
+ *
+ * app.use('/api', baserowExpress.baserowAuth(config))
+ * app.use('/api', baserowExpress.requireAuth())
+ *
+ * app.get('/api/protected', async (req, res) => {
+ *   // req.baserow está garantizado aquí
+ *   const data = await req.baserow!.database(123).table(456).rows.list()
+ *   res.json(data)
+ * })
+ * ```
+ */
+export function requireAuth(): ExpressMiddleware {
+  return async (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => {
+    try {
+      if (!req.baserow) {
+        res.status(401).json({
+          error: 'Baserow client not found. Use baserowAuth() middleware first.',
+          code: 'BASEROW_CLIENT_MISSING'
+        })
+        return
+      }
+
+      // Opcional: verificar conectividad
+      const isConnected = await req.baserow.health()
+      if (!isConnected) {
+        res.status(503).json({
+          error: 'Baserow server not accessible',
+          code: 'BASEROW_UNAVAILABLE'
+        })
+        return
+      }
+
+      next()
+    } catch (error) {
+      next(error)
+    }
+  }
+}
+
+/**
+ * Middleware para cleanup automático de recursos Baserow
+ *
+ * Limpia el cliente Baserow al final del request para evitar memory leaks.
+ * Especialmente útil cuando se usan clientes per-request.
+ *
+ * @returns Middleware Express
+ *
+ * @example
+ * ```typescript
+ * import { express as baserowExpress } from '@gzl10/baserow'
+ *
+ * app.use('/api', baserowExpress.baserowAuth(config))
+ * // ... otras rutas ...
+ * app.use('/api', baserowExpress.baserowCleanup()) // Debe ir al final
+ * ```
+ */
+export function baserowCleanup(): ExpressMiddleware {
+  return (req: ExpressRequest, _res: ExpressResponse, next: ExpressNextFunction) => {
+    // Cleanup después de que la respuesta se envíe
+    if (req.baserow) {
+      const cleanup = () => {
+        try {
+          req.baserow?.destroy()
+          delete req.baserow
+        } catch (error) {
+          // Log error pero no fallar el request
+          // eslint-disable-next-line no-console
+          console.warn('Error cleaning up Baserow client:', error)
+        }
+      }
+
+      // Cleanup en el próximo tick después de enviar response
+      process.nextTick(cleanup)
+    }
+
+    next()
+  }
+}