@gzl10/baserow 1.2.0

package/src/types/auth.ts

@@ -0,0 +1,177 @@
+/**
+ * Tipos relacionados con autenticación y configuración
+ */
+
+import { Logger } from './core'
+
+export interface BaserowCredentials {
+  email: string
+  password: string
+}
+
+/**
+ * Opciones de configuración de rendimiento (completamente opcionales)
+ *
+ * Permite personalizar el comportamiento del cliente HTTP para casos específicos:
+ * - Testing: timeouts largos, pocos reintentos
+ * - Batch operations: rate limiting alto, timeouts largos
+ * - Producción crítica: configuración conservadora
+ *
+ * @since 1.2.0
+ */
+export interface BaserowPerformanceOptions {
+  /** Timeout por request en milisegundos (default: 30000) */
+  timeout?: number
+  /** Número de reintentos automáticos (default: 3) */
+  retries?: number
+  /** Máximo requests por segundo para rate limiting (default: 10) */
+  maxRequestsPerSecond?: number
+  /** Habilitar rate limiting automático (default: true) */
+  enableRateLimiting?: boolean
+}
+
+/**
+ * Configuración de keep-alive para evitar expiración de refresh token
+ *
+ * IMPORTANTE: El refresh token de Baserow expira 7 días después del login (fijo, NO se renueva con refresh).
+ * Keep-alive ejecuta RE-LOGIN completo periódicamente para obtener tokens frescos y mantener
+ * la sesión activa indefinidamente en aplicaciones backend de larga duración (24/7).
+ *
+ * ⚠️ SEGURIDAD: Las credenciales se almacenan en memoria del proceso.
+ * Solo habilitar en backends propios/confiables, NO en frontends o apps compartidas.
+ *
+ * @example
+ * ```typescript
+ * // Re-login cada 5 días (default recomendado, margen de 2 días)
+ * keepAlive: { enabled: true }
+ *
+ * // Re-login cada 3 días (más conservador, margen de 4 días)
+ * keepAlive: { enabled: true, intervalMinutes: 4320 }
+ * ```
+ *
+ * @since 1.3.0
+ */
+export interface KeepAliveConfig {
+  /** Habilitar keep-alive automático (almacena credenciales en memoria) */
+  enabled: true
+  /** Intervalo en minutos para re-login (default: 7200 = 5 días) */
+  intervalMinutes?: number
+}
+
+export interface BaserowConfig {
+  url: string
+  token: string
+  logger?: Logger
+  /** Configuración opcional de rendimiento */
+  performance?: BaserowPerformanceOptions
+}
+
+export interface BaserowAdminConfig {
+  url: string
+  credentials: BaserowCredentials
+  workspace?: string
+  logger?: Logger
+  /** Configuración opcional de rendimiento */
+  performance?: BaserowPerformanceOptions
+  /** Configuración opcional de keep-alive para evitar expiración de refresh token */
+  keepAlive?: KeepAliveConfig
+}
+
+export interface LoginRequest {
+  username: string
+  password: string
+}
+
+export interface LoginResponse {
+  token: string
+  access_token: string
+  refresh_token: string
+  user_session: string
+  user: {
+    id: number
+    username: string
+    first_name: string
+    email_verified: boolean
+    is_staff: boolean
+    language: string
+    completed_onboarding: boolean
+  }
+}
+
+export interface RefreshTokenRequest {
+  refresh_token: string
+}
+
+export interface RefreshTokenResponse {
+  token: string
+  access_token: string
+  user: {
+    id: number
+    username: string
+    first_name: string
+    email_verified: boolean
+    is_staff: boolean
+    language: string
+    completed_onboarding: boolean
+  }
+}
+
+export interface ChangePasswordRequest {
+  old_password: string
+  new_password: string
+}
+
+// ===== Nuevos tipos para API unificada =====
+
+/**
+ * Configuración para cliente con Database Token
+ */
+export interface BaserowTokenConfig {
+  url: string
+  token: string
+  logger?: Logger
+  performance?: BaserowPerformanceOptions
+}
+
+/**
+ * Configuración para cliente con credenciales (sin workspace específico)
+ */
+export interface BaserowCredentialsConfig {
+  url: string
+  credentials: BaserowCredentials
+  logger?: Logger
+  performance?: BaserowPerformanceOptions
+  keepAlive?: KeepAliveConfig
+}
+
+/**
+ * Configuración para cliente con credenciales y workspace específico
+ */
+export interface BaserowCredentialsWorkspaceConfig extends BaserowCredentialsConfig {
+  workspace: string
+}
+
+/**
+ * Configuración unificada que puede ser cualquiera de los tipos anteriores
+ */
+export type BaserowUnifiedConfig = BaserowTokenConfig | BaserowCredentialsConfig | BaserowCredentialsWorkspaceConfig
+
+// ===== Aliases descriptivos para mejor DX =====
+
+/**
+ * Alias: Configuración para cliente con Database Token
+ * @alias BaserowTokenConfig
+ */
+export type TokenConfig = BaserowTokenConfig
+
+/**
+ * Alias: Configuración para cliente con credenciales (sin workspace específico)
+ * @alias BaserowCredentialsConfig
+ */
+export type CredentialsConfig = BaserowCredentialsConfig
+
+/**
+ * Alias: Configuración para cliente con credenciales y workspace específico
+ * @alias BaserowCredentialsWorkspaceConfig
+ */
+export type CredentialsWorkspaceConfig = BaserowCredentialsWorkspaceConfig

package/src/types/core.ts

@@ -0,0 +1,91 @@
+/**
+ * Tipos fundamentales y entidades core de Baserow
+ */
+
+export interface Logger {
+  info(message?: any, ...optionalParams: any[]): void
+  warn(message?: any, ...optionalParams: any[]): void
+  error(message?: any, ...optionalParams: any[]): void
+  debug?(message?: any, ...optionalParams: any[]): void
+  log?(message?: any, ...optionalParams: any[]): void
+}
+
+export interface UserReference {
+  id: number
+  email: string
+  name: string
+  permissions: string
+  to_be_deleted: boolean
+  user_id: number
+  workspace: number
+  created_on: Date
+}
+
+export interface Workspace {
+  id: number
+  name: string
+  order: number
+  permissions: string
+  users: UserReference[]
+}
+
+export interface Database {
+  id: number
+  name: string
+  order: number
+  type: string
+  workspace?: {
+    id: number
+    name: string
+  }
+  tables: Table[]
+  created_on?: string
+}
+
+export interface DatabaseLight {
+  id: number
+  name: string
+  order: number
+  database_id: number
+}
+
+/**
+ * Tabla tal como viene del endpoint /database/tables/all-tables/
+ * Usado para Database Tokens que pueden listar tablas directamente
+ */
+export interface TableFromAllTables {
+  id: number
+  name: string
+  order: number
+  database_id: number
+}
+
+export interface Table {
+  id: number
+  name: string
+  order: number
+  database_id: number
+}
+
+export interface Row {
+  id: number
+  order: string
+  [fieldName: string]: any
+}
+
+export interface User {
+  id: number
+  username: string
+  first_name: string
+  last_name?: string
+  email_verified: boolean
+  is_staff: boolean
+  is_active: boolean
+  language: string
+  completed_onboarding: boolean
+  created_on: string
+}
+
+export interface UserProfile extends User {
+  email_notification_frequency: string
+}

package/src/types/errors.ts

@@ -0,0 +1,105 @@
+/**
+ * Clases de error específicas para Baserow
+ */
+
+export class BaserowError extends Error {
+  public config?: any // Axios request config para permitir retry en interceptores
+
+  constructor(
+    message: string,
+    public status?: number,
+    public code?: string,
+    public details?: any,
+    config?: any
+  ) {
+    super(message)
+    this.name = 'BaserowError'
+    this.config = config
+  }
+}
+
+export class BaserowValidationError extends BaserowError {
+  constructor(
+    message: string,
+    public fieldErrors: Record<string, string[]>
+  ) {
+    super(message, 400, 'VALIDATION_ERROR', fieldErrors)
+    this.name = 'BaserowValidationError'
+  }
+}
+
+export class BaserowNotFoundError extends BaserowError {
+  constructor(resource: string, id: number | string) {
+    super(`${resource} with id ${id} not found`, 404, 'NOT_FOUND')
+    this.name = 'BaserowNotFoundError'
+  }
+}
+
+export class BaserowRateLimitError extends BaserowError {
+  constructor(public retryAfter?: number) {
+    super('Rate limit exceeded', 429, 'RATE_LIMIT', { retryAfter })
+    this.name = 'BaserowRateLimitError'
+  }
+}
+
+export class BaserowNetworkError extends BaserowError {
+  constructor(message: string, originalError?: any) {
+    super(`Network error: ${message}`, 0, 'NETWORK_ERROR', { originalError })
+    this.name = 'BaserowNetworkError'
+  }
+}
+
+export class BaserowTimeoutError extends BaserowError {
+  constructor(timeoutMs: number) {
+    super(`Request timeout after ${timeoutMs}ms`, 0, 'TIMEOUT', { timeoutMs })
+    this.name = 'BaserowTimeoutError'
+  }
+}
+
+export class BaserowConfigError extends BaserowError {
+  constructor(message: string, configField?: string) {
+    super(`Configuration error: ${message}`, 0, 'CONFIG_ERROR', { configField })
+    this.name = 'BaserowConfigError'
+  }
+}
+
+export class BaserowWorkspaceError extends BaserowError {
+  constructor(message: string, workspaceId?: number) {
+    super(`Workspace error: ${message}`, 0, 'WORKSPACE_ERROR', { workspaceId })
+    this.name = 'BaserowWorkspaceError'
+  }
+}
+
+export class BaserowAuthTokenExpiredError extends BaserowError {
+  constructor(tokenType: 'access' | 'refresh' = 'refresh') {
+    super(
+      `${tokenType === 'access' ? 'Access' : 'Refresh'} token has expired. Please login again.`,
+      401,
+      'AUTH_TOKEN_EXPIRED',
+      { tokenType }
+    )
+    this.name = 'BaserowAuthTokenExpiredError'
+  }
+}
+
+export class BaserowAuthTokenInvalidError extends BaserowError {
+  constructor(message: string = 'Invalid or corrupted authentication token', details?: any) {
+    super(message, 401, 'AUTH_TOKEN_INVALID', details)
+    this.name = 'BaserowAuthTokenInvalidError'
+  }
+}
+
+export class BaserowReLoginRequiredError extends BaserowError {
+  constructor(
+    reason: 'refresh_token_expired' | 'session_expired' | 'tokens_lost' = 'refresh_token_expired',
+    details?: any
+  ) {
+    const messages = {
+      refresh_token_expired: 'Refresh token has expired after period of inactivity. Re-authentication required.',
+      session_expired: 'Session has expired. Please login again with your credentials.',
+      tokens_lost: 'Authentication tokens were lost (process restart or memory cleared). Re-authentication required.'
+    }
+    super(messages[reason], 401, 'RE_LOGIN_REQUIRED', { reason, ...details })
+    this.name = 'BaserowReLoginRequiredError'
+  }
+}