@gzl10/baserow 1.2.0

package/src/services/DatabaseService.ts

@@ -0,0 +1,246 @@
+import { HttpService } from './core/HttpService'
+import { ValidationService } from './core/ValidationService'
+import { Database, BaserowResponse, BaserowNotFoundError, Logger } from '../types/index'
+
+/**
+ * Servicio para operaciones CRUD de databases de Baserow
+ *
+ * Proporciona operaciones completas de databases (aplicaciones) incluyendo
+ * CRUD básico, búsqueda por nombre y gestión dentro de workspaces.
+ * Las databases son contenedores de tablas en la jerarquía de Baserow.
+ *
+ * **Características:**
+ * - CRUD completo: create, read, update, delete
+ * - Búsqueda de databases por nombre
+ * - Gestión por workspace
+ * - Validación de nombres y IDs
+ * - Manejo robusto de errores
+ *
+ * **Jerarquía de Baserow:**
+ * ```
+ * Workspace → Database → Table → Field/Row
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Operaciones básicas
+ * const databases = await databaseService.list()
+ * const database = await databaseService.findUnique(123)
+ *
+ * // Búsqueda y gestión
+ * const found = await databaseService.findDatabaseByName('Mi Database')
+ * const newDb = await databaseService.createDatabase(workspaceId, 'Nueva DB')
+ * await databaseService.updateDatabase(dbId, { name: 'Nuevo Nombre' })
+ * await databaseService.delete(dbId)
+ * ```
+ *
+ * @since 1.0.0
+ */
+export class DatabaseService extends HttpService {
+  private validationService: ValidationService
+  private defaultWorkspaceId?: number
+
+  constructor(http: any, logger?: Logger, defaultWorkspaceId?: number) {
+    super(http, logger)
+    this.validationService = new ValidationService(http, logger)
+    this.defaultWorkspaceId = defaultWorkspaceId
+  }
+
+  // ===== PUBLIC API (Prisma-style) =====
+
+  /**
+   * Listar todas las databases accesibles
+   *
+   * Obtiene todas las databases a las que el token tiene acceso.
+   * Con JWT devuelve todas las databases del usuario, con Database Token
+   * solo las databases permitidas por el token.
+   *
+   * @returns Promise con array de databases
+   *
+   * @example
+   * ```typescript
+   * const databases = await databaseService.findMany()
+   * databases.forEach(db => {
+   *   console.log(`${db.name} (ID: ${db.id}) - ${db.tables?.length || 0} tablas`)
+   * })
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async findMany(): Promise<Database[]> {
+    try {
+      // JWT API devuelve array directo, Database Token API devuelve {results: [...]}
+      const response = await this.http.get<BaserowResponse<Database> | Database[]>('/applications/')
+      const databases = Array.isArray(response) ? response : response.results
+
+      this.logSuccess('list databases', undefined, { count: databases.length })
+      return databases || []
+    } catch (error) {
+      this.handleHttpError(error, 'list databases')
+    }
+  }
+
+  /**
+   * Buscar database por ID o nombre
+   *
+   * Busca una database específica por su ID o nombre dentro de todas las
+   * databases accesibles. Útil para operaciones dinámicas donde se
+   * conoce el identificador pero no se sabe si es ID o nombre.
+   *
+   * @param identifier - ID numérico o nombre de la database a buscar
+   * @returns Promise con la database encontrada o null si no existe
+   *
+   * @throws {BaserowValidationError} Si el identificador es inválido
+   *
+   * @example
+   * ```typescript
+   * const database = await databaseService.findUnique('CRM')
+   * if (database) {
+   *   console.log(`Database encontrada: ${database.id}`)
+   * } else {
+   *   console.log('Database no encontrada')
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async findUnique(identifier: string | number): Promise<Database | null> {
+    if (typeof identifier === 'number') {
+      // Buscar por ID
+      try {
+        this.validationService.validateId(identifier, 'database ID')
+        return await this.getById<Database>('/applications', identifier)
+      } catch (error) {
+        if (error instanceof BaserowNotFoundError) {
+          return null
+        }
+        throw error
+      }
+    } else {
+      // Buscar por nombre
+      this.validationService.validateResourceName(identifier, 'database')
+      const databases = await this.findMany()
+      const found = databases.find(db => db.name === identifier) || null
+
+      if (found) {
+        this.logSuccess(`find database by name "${identifier}"`, found.id)
+      } else {
+        this.logDebug(`No database found with name "${identifier}"`)
+      }
+
+      return found
+    }
+  }
+
+  /**
+   * Crear nueva database - API pública
+   *
+   * Crea una nueva database dentro del workspace especificado o usa el workspace por defecto.
+   * La database se crea vacía sin tablas iniciales.
+   *
+   * @param workspaceIdOrName - ID numérico del workspace donde crear la database, o nombre si hay workspace por defecto
+   * @param name - Nombre de la nueva database (opcional si el primer parámetro es nombre)
+   * @returns Promise con la database creada
+   *
+   * @throws {BaserowValidationError} Si los parámetros son inválidos
+   *
+   * @example
+   * ```typescript
+   * // Con workspace específico
+   * const newDatabase = await databaseService.create(456, 'Nueva Database')
+   *
+   * // Con workspace por defecto (ClientWithCredsWs)
+   * const newDatabase = await databaseService.create('Nueva Database')
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async create(workspaceIdOrName: number | string, name?: string): Promise<Database> {
+    if (typeof workspaceIdOrName === 'number') {
+      // Caso tradicional: create(workspaceId, name)
+      if (!name) {
+        throw new Error('Database name is required when providing workspace ID')
+      }
+      return this.createDatabaseInternal(workspaceIdOrName, name)
+    } else {
+      // Caso nuevo: create(name) usando workspace por defecto
+      if (!this.defaultWorkspaceId) {
+        throw new Error('No default workspace configured. Use create(workspaceId, name) instead')
+      }
+      return this.createDatabaseInternal(this.defaultWorkspaceId, workspaceIdOrName)
+    }
+  }
+
+  // ===== PRIVATE METHODS =====
+
+  /**
+   * Crear nueva database (método interno)
+   * @private - Solo para uso interno del servicio
+   */
+  private async createDatabaseInternal(workspaceId: number, name: string): Promise<Database> {
+    this.validationService.validateId(workspaceId, 'workspace ID')
+    this.validationService.validateResourceName(name, 'database')
+
+    const requestData = {
+      type: 'database',
+      name
+    }
+
+    try {
+      this.logDebug(`Creating database "${name}" in workspace ${workspaceId}`, requestData)
+      const response = await this.http.post<Database>(`/applications/workspace/${workspaceId}/`, requestData)
+      this.logSuccess('create database', response.id, { name: name })
+      return response
+    } catch (error) {
+      this.handleHttpError(error, 'create database')
+    }
+  }
+
+  /**
+   * Actualizar database existente (método interno)
+   * @private - Solo para uso por DatabaseContext
+   */
+  private async updateDatabaseInternal(id: number, data: { name?: string; workspace_id?: number }): Promise<Database> {
+    this.validationService.validateId(id, 'database ID')
+
+    if (data.name) {
+      this.validationService.validateResourceName(data.name, 'database')
+    }
+
+    try {
+      this.logDebug(`Updating database ${id}`, data)
+      const response = await this.http.patch<Database>(`/applications/${id}/`, data)
+      this.logSuccess('update database', id)
+      return response
+    } catch (error) {
+      if ((error as any).status === 404) {
+        throw new BaserowNotFoundError('Database', id)
+      }
+      this.handleHttpError(error, 'update database', id)
+    }
+  }
+
+  /**
+   * Eliminar database (método interno)
+   * @private - Solo para uso por DatabaseContext
+   */
+  private async deleteDatabaseInternal(id: number): Promise<void> {
+    this.validationService.validateId(id, 'database ID')
+    return this.deleteById('/applications', id)
+  }
+
+  // ===== FRIEND ACCESS PATTERN FOR DATABASE CONTEXT =====
+  // Symbol-based access que no aparece en la API pública pero permite acceso interno
+
+  /**
+   * Friend access para DatabaseContext
+   * No aparece en intellisense normal ni en la API pública
+   * @internal
+   */
+  get [Symbol.for('databaseContext')]() {
+    return {
+      updateDatabase: this.updateDatabaseInternal.bind(this),
+      deleteDatabase: this.deleteDatabaseInternal.bind(this)
+    }
+  }
+}

package/src/services/DatabaseTokenService.ts

@@ -0,0 +1,186 @@
+import { HttpService } from './core/HttpService'
+import { ValidationService } from './core/ValidationService'
+import {
+  DatabaseToken,
+  DatabaseTokenPermissions,
+  CreateDatabaseTokenRequest,
+  UpdateDatabaseTokenRequest,
+  BaserowResponse,
+  BaserowNotFoundError,
+  Logger
+} from '../types/index'
+import { validateString } from '../utils/validation'
+
+export class DatabaseTokenService extends HttpService {
+  private validationService: ValidationService
+
+  constructor(http: any, logger?: Logger) {
+    super(http, logger)
+    this.validationService = new ValidationService(http, logger)
+  }
+
+  /**
+   * Listar database tokens de un workspace
+   */
+  async list(workspaceId: number): Promise<DatabaseToken[]> {
+    this.validationService.validateId(workspaceId, 'workspace ID')
+
+    try {
+      const response = await this.http.get<BaserowResponse<any> | any[]>(`/database/tokens/`, {
+        params: { workspace_id: workspaceId }
+      })
+
+      // La API puede devolver array directo o {results: []}
+      const rawTokens = Array.isArray(response) ? response : response.results || []
+      // Mapear key → token para consistencia en la interfaz
+      const tokens = rawTokens.map((token: any) => ({ ...token, token: token.key || '' }))
+      this.logSuccess('list database tokens', workspaceId, { count: tokens.length })
+      return tokens
+    } catch (error) {
+      this.handleHttpError(error, 'list database tokens', workspaceId)
+    }
+  }
+
+  /**
+   * Obtener database token por ID
+   */
+  async get(tokenId: number): Promise<DatabaseToken> {
+    this.validationService.validateId(tokenId, 'token ID')
+    const response = await this.getById<any>('/database/tokens', tokenId)
+    return { ...response, token: response.key || '' }
+  }
+
+  /**
+   * Obtener database token por su valor (key)
+   * Busca en la lista de tokens del workspace correspondiente
+   */
+  async getToken(tokenValue: string): Promise<DatabaseToken> {
+    validateString(tokenValue, 'token value')
+
+    try {
+      this.logDebug(`Getting database token by value`, { tokenPreview: tokenValue.substring(0, 8) + '...' })
+
+      // Como no hay endpoint directo, buscamos en todas las listas de workspaces
+      // Este es un método menos eficiente pero funcional
+      throw new Error('getToken requires workspace ID - use context.getToken() instead')
+    } catch (error) {
+      this.handleHttpError(error, 'get database token by value', tokenValue)
+    }
+  }
+
+  /**
+   * Crear nuevo database token
+   *
+   * NOTA: La API de Baserow tiene un comportamiento específico:
+   * 1. Al crear el token, siempre establece TODOS los permisos en `true`
+   * 2. Para aplicar permisos específicos, se requiere una actualización posterior
+   *
+   * Esta implementación maneja automáticamente este comportamiento:
+   * - POST /database/tokens/ → crea token con permisos completos
+   * - PATCH /database/tokens/{id}/ → ajusta permisos al valor deseado
+   */
+  async createToken(workspaceId: number, data: CreateDatabaseTokenRequest): Promise<DatabaseToken> {
+    this.validationService.validateId(workspaceId, 'workspace ID')
+    this.validationService.validateResourceName(data.name, 'token')
+
+    if (!data.permissions) {
+      throw new Error('Database token permissions are required')
+    }
+
+    const payload = {
+      workspace: workspaceId,
+      ...data
+    }
+
+    try {
+      this.logDebug(`Creating database token "${data.name}" for workspace ${workspaceId}`, payload)
+      // 1. Crear token (la API establece automáticamente permisos completos)
+      const response = await this.http.post<any>(`/database/tokens/`, payload)
+      if (!response.key) throw new Error('Database token key is missing')
+      response.token = response.key
+      // 2. Actualizar permisos al valor deseado (si no son permisos completos)
+      const needsPermissionUpdate = !this.hasFullPermissions(data.permissions)
+      if (needsPermissionUpdate) {
+        const updatedToken = await this.updateToken(response.id, { permissions: data.permissions })
+        this.logSuccess('create database token', response.id, { name: data.name, workspace: workspaceId })
+        return updatedToken
+      }
+      this.logSuccess('create database token', response.id, { name: data.name, workspace: workspaceId })
+      return { ...response, token: response.key, permissions: data.permissions }
+    } catch (error) {
+      this.handleHttpError(error, 'create database token', workspaceId)
+    }
+  }
+
+  /**
+   * Verificar si los permisos dados son permisos completos (todos true)
+   */
+  private hasFullPermissions(permissions: DatabaseTokenPermissions): boolean {
+    return permissions.create && permissions.read && permissions.update && permissions.delete
+  }
+
+  /**
+   * Actualizar database token
+   */
+  async updateToken(tokenId: number, data: UpdateDatabaseTokenRequest): Promise<DatabaseToken> {
+    this.validationService.validateId(tokenId, 'token ID')
+
+    if (data.name !== undefined) {
+      this.validationService.validateResourceName(data.name, 'token')
+    }
+
+    try {
+      this.logDebug(`Updating database token ${tokenId}`, data)
+      const response = await this.http.patch<any>(`/database/tokens/${tokenId}/`, data)
+      this.logSuccess('update database token', tokenId)
+      return { ...response, token: response.key || '' }
+    } catch (error) {
+      if ((error as any).status === 404) {
+        throw new BaserowNotFoundError('Database Token', tokenId)
+      }
+      this.handleHttpError(error, 'update database token', tokenId)
+    }
+  }
+
+  /**
+   * Eliminar database token
+   */
+  async delete(tokenId: number): Promise<void> {
+    this.validationService.validateId(tokenId, 'token ID')
+    return this.deleteById('/database/tokens', tokenId)
+  }
+
+  /**
+   * Verificar si un database token existe
+   */
+  async exists(tokenId: number): Promise<boolean> {
+    try {
+      await this.get(tokenId)
+      return true
+    } catch (error) {
+      if (error instanceof BaserowNotFoundError) {
+        return false
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Buscar database token por nombre en un workspace
+   */
+  async findByName(workspaceId: number, name: string): Promise<DatabaseToken | null> {
+    this.validationService.validateId(workspaceId, 'workspace ID')
+    this.validationService.validateResourceName(name, 'token')
+
+    const tokens = await this.list(workspaceId)
+    const found = tokens.find(token => token.name === name) || null
+
+    if (found) {
+      this.logSuccess(`find database token by name "${name}"`, found.id)
+    } else {
+      this.logDebug(`No database token found with name "${name}" in workspace ${workspaceId}`)
+    }
+
+    return found
+  }
+}