@gzl10/baserow 1.2.0

package/src/contexts/TableOnlyContext.ts

@@ -0,0 +1,74 @@
+import { Logger } from '../types'
+import { TableClientContext } from './TableClientContext'
+import { RowOnlyContext } from './RowContext'
+import { TableService } from '../services/TableService'
+import { FieldService } from '../services/FieldService'
+import { RowService } from '../services/RowService'
+
+/**
+ * Context para acceso directo a una tabla específica con Database Token
+ *
+ * A diferencia de TableContext que requiere database context, este contexto
+ * permite acceso directo a una tabla específica usando solo su ID.
+ * Diseñado para Database Tokens que ya conocen los IDs de tabla específicos.
+ */
+export class TableOnlyContext {
+  private tableId: number
+  private logger?: Logger
+
+  constructor(
+    tableId: number,
+    private tableService: TableService,
+    private fieldService: FieldService,
+    private rowService: RowService,
+    logger?: Logger
+  ) {
+    this.tableId = tableId
+    this.logger = logger
+  }
+
+  /**
+   * Obtener información de la tabla
+   */
+  async get() {
+    return await this.tableService.get(this.tableId)
+  }
+
+  /**
+   * Verificar si la tabla existe
+   */
+  async exists(): Promise<boolean> {
+    return await this.tableService.exists(this.tableId)
+  }
+
+  /**
+   * Acceso a operaciones de filas de esta tabla
+   */
+  get rows() {
+    return new TableClientContext(
+      0, // databaseId no se usa en operaciones de rows con Database Token
+      this.tableId,
+      this.tableService,
+      this.fieldService,
+      this.rowService,
+      this.logger
+    ).rows
+  }
+
+  /**
+   * Acceso a una fila específica por ID
+   *
+   * @param rowId - ID de la fila
+   * @returns Contexto de fila individual para operaciones CRUD
+   *
+   * @example
+   * ```typescript
+   * const row = await client.table(123).row(456).get()
+   * await client.table(123).row(456).update({ name: 'Nuevo nombre' })
+   * await client.table(123).row(456).delete()
+   * ```
+   */
+  row(rowId: number): RowOnlyContext {
+    return new RowOnlyContext(this.tableId, rowId, this.rowService, this.logger)
+  }
+}

package/src/contexts/WorkspaceContext.ts

@@ -0,0 +1,490 @@
+import { Logger, Workspace, BaserowNotFoundError, Database } from '../types'
+import { DatabaseContext } from './DatabaseContext'
+import { DatabaseTokenContext } from './DatabaseTokenContext'
+import { WorkspaceService, UpdateWorkspaceRequest } from '../services/WorkspaceService'
+import { DatabaseService } from '../services/DatabaseService'
+import { DatabaseTokenService } from '../services/DatabaseTokenService'
+import { TableService } from '../services/TableService'
+import { FieldService } from '../services/FieldService'
+import { RowService } from '../services/RowService'
+
+/**
+ * Context para operaciones en un workspace específico
+ *
+ * Proporciona una API jerárquica fluida para operaciones administrativas
+ * dentro de un workspace específico. Permite el acceso encadenado
+ * workspace → database → table → field/rows y operaciones CRUD completas.
+ *
+ * **Características principales:**
+ * - Resolución automática de workspace por nombre o ID (lazy loading)
+ * - API fluida para operaciones de databases: list, find, create
+ * - Operaciones CRUD del workspace: update, delete
+ * - Acceso directo a database contexts específicos
+ * - Gestión de database tokens del workspace
+ * - Cache interno para evitar resoluciones repetidas
+ * - Logging opcional de todas las operaciones
+ *
+ * **Patrón de API Jerárquica:**
+ * ```
+ * workspace.databases.list()           // Operaciones masivas
+ * workspace.database('name')           // Context específico
+ * workspace.databaseToken              // Database tokens
+ * workspace.update({ name: 'nuevo' })  // Actualizar workspace
+ * workspace.delete()                   // Eliminar workspace
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Gestión del workspace
+ * const updated = await workspace.update({ name: 'Nuevo Nombre' })
+ * await workspace.delete()  // Elimina workspace y todo su contenido
+ *
+ * // Operaciones básicas de databases
+ * const databases = await workspace.databases.list()
+ * const newDb = await workspace.databases.create('Nueva Database')
+ * const found = await workspace.databases.find('Existente')
+ *
+ * // Acceso jerárquico a database
+ * const dbContext = workspace.database('Mi Database')
+ * const table = await dbContext.tables.create({ name: 'Mi Tabla' })
+ *
+ * // Gestión de database tokens
+ * const tokens = await workspace.databaseToken.list()
+ * const token = await workspace.databaseToken.create('read', ['table1'])
+ * ```
+ *
+ * @since 1.0.0
+ */
+export class WorkspaceContext {
+  private workspaceIdentifier: string | number
+  private resolvedWorkspace?: Workspace
+  private logger?: Logger
+
+  /**
+   * Crea un nuevo context de workspace
+   *
+   * El constructor es interno y no debe ser llamado directamente.
+   * Usar `admin.workspace(nameOrId)` para crear contextos de workspace.
+   *
+   * @param workspaceService - Servicio para operaciones de workspace (CRUD completo)
+   * @param databaseService - Servicio para operaciones de database
+   * @param databaseTokenService - Servicio para gestión de tokens
+   * @param tableService - Servicio para operaciones de tabla
+   * @param fieldService - Servicio para operaciones de campos
+   * @param rowService - Servicio para operaciones de filas
+   * @param workspaceIdentifier - Nombre (string) o ID (number) del workspace
+   * @param logger - Logger opcional para debug y trazabilidad
+   *
+   * @example Uso típico del contexto
+   * ```typescript
+   * // Creación del contexto (interno)
+   * const workspaceContext = admin.workspace('Mi Empresa')
+   *
+   * // Operaciones CRUD del workspace
+   * const updated = await workspaceContext.update({ name: 'Nueva Empresa' })
+   * await workspaceContext.delete()
+   *
+   * // Operaciones de databases
+   * const databases = await workspaceContext.databases.list()
+   * const dbContext = workspaceContext.database('CRM')
+   * ```
+   *
+   * @internal
+   * @since 1.0.0
+   */
+  constructor(
+    private workspaceService: WorkspaceService,
+    private databaseService: DatabaseService,
+    private databaseTokenService: DatabaseTokenService,
+    private tableService: TableService,
+    private fieldService: FieldService,
+    private rowService: RowService,
+    workspaceIdentifier: string | number,
+    logger?: Logger
+  ) {
+    this.workspaceIdentifier = workspaceIdentifier
+    this.logger = logger
+  }
+
+  /**
+   * Operaciones masivas de databases en este workspace
+   *
+   * Proporciona métodos para gestionar databases de forma masiva:
+   * listar todas, buscar por nombre y crear nuevas databases.
+   * Todas las operaciones están restringidas al workspace actual.
+   *
+   * @returns Objeto con métodos para operaciones de databases
+   *
+   * @example
+   * ```typescript
+   * // Listar todas las databases del workspace
+   * const databases = await workspace.databases.list()
+   *
+   * // Buscar database específica
+   * const db = await workspace.databases.find('Mi Database')
+   *
+   * // Crear nueva database
+   * const newDb = await workspace.databases.create('Nueva Database')
+   * ```
+   *
+   * @since 1.0.0
+   */
+  get databases() {
+    return {
+      /**
+       * Listar todas las databases del workspace
+       *
+       * Obtiene todas las databases que pertenecen a este workspace.
+       * Filtra automáticamente las databases globales para mostrar
+       * solo las del workspace actual.
+       *
+       * @returns Promise con array de databases del workspace
+       *
+       * @example
+       * ```typescript
+       * const databases = await workspace.databases.list()
+       * console.log(`Encontradas ${databases.length} databases`)
+       * databases.forEach(db => {
+       *   console.log(`${db.name} (ID: ${db.id})`)
+       * })
+       * ```
+       *
+       * @since 1.0.0
+       */
+      list: async (): Promise<Database[]> => {
+        const workspace = await this.get()
+        const allDatabases = await this.databaseService.findMany()
+        return allDatabases.filter(db => db.workspace?.id === workspace.id)
+      },
+
+      /**
+       * Buscar database por nombre en este workspace
+       *
+       * Busca una database específica por nombre dentro del workspace.
+       * Útil para operaciones donde se conoce el nombre pero no el ID.
+       *
+       * @param name - Nombre exacto de la database a buscar
+       * @returns Promise con la database encontrada o null si no existe
+       *
+       * @example
+       * ```typescript
+       * const db = await workspace.databases.find('CRM')
+       * if (db) {
+       *   console.log(`Database encontrada: ${db.id}`)
+       * } else {
+       *   console.log('Database no encontrada')
+       * }
+       * ```
+       *
+       * @since 1.0.0
+       */
+      find: async (name: string): Promise<Database | null> => {
+        const databases = await this.databases.list()
+        return databases.find(db => db.name === name) || null
+      },
+
+      /**
+       * Crear nueva database en este workspace
+       *
+       * Crea una nueva database vacía en este workspace.
+       * La database se crea sin tablas iniciales.
+       *
+       * @param name - Nombre de la nueva database
+       * @returns Promise con la database creada
+       *
+       * @throws {BaserowValidationError} Si el nombre es inválido
+       *
+       * @example
+       * ```typescript
+       * const newDb = await workspace.databases.create('Nueva Database')
+       * console.log(`Database creada: ${newDb.id} - ${newDb.name}`)
+       * ```
+       *
+       * @since 1.0.0
+       */
+      create: async (name: string): Promise<Database> => {
+        const workspace = await this.get()
+        return await this.databaseService.create(workspace.id, name)
+      }
+    }
+  }
+
+  /**
+   * Acceder a una base de datos específica en este workspace
+   *
+   * Crea un context para operaciones específicas en una database.
+   * Permite acceso jerárquico a tablas, campos y filas de la database.
+   * El identificador puede ser nombre (string) o ID (number).
+   *
+   * @param databaseIdentifier - Nombre o ID numérico de la database
+   * @returns Context de database para operaciones específicas
+   *
+   * @example
+   * ```typescript
+   * // Acceso por nombre
+   * const dbContext = workspace.database('Mi Database')
+   *
+   * // Acceso por ID
+   * const dbContext2 = workspace.database(123)
+   *
+   * // Operaciones jerárquicas
+   * const tables = await dbContext.tables.findMany()
+   * const table = await dbContext.tables.create({ name: 'Nueva Tabla' })
+   * ```
+   *
+   * @since 1.0.0
+   */
+  database(databaseIdentifier: string | number): DatabaseContext {
+    return new DatabaseContext(
+      this.workspaceService,
+      this.workspaceIdentifier,
+      databaseIdentifier,
+      this.databaseService,
+      this.tableService,
+      this.fieldService,
+      this.rowService,
+      this.logger
+    )
+  }
+
+  /**
+   * Operaciones de database tokens en este workspace
+   *
+   * Proporciona acceso al context de database tokens para gestionar
+   * tokens de acceso específicos del workspace. Los database tokens
+   * permiten acceso limitado a databases y tablas específicas.
+   *
+   * @returns Context de database tokens
+   *
+   * @example
+   * ```typescript
+   * // Listar tokens existentes
+   * const tokens = await workspace.databaseToken.list()
+   *
+   * // Crear token de solo lectura
+   * const readToken = await workspace.databaseToken.create(
+   *   'read',
+   *   ['table1', 'table2']
+   * )
+   *
+   * // Crear token de escritura
+   * const writeToken = await workspace.databaseToken.create(
+   *   'create',
+   *   ['table1']
+   * )
+   * ```
+   *
+   * @since 1.0.0
+   */
+  get databaseToken(): DatabaseTokenContext {
+    return new DatabaseTokenContext(
+      this.workspaceService,
+      this.workspaceIdentifier,
+      this.databaseTokenService,
+      this.logger
+    )
+  }
+
+  /**
+   * Actualizar este workspace
+   *
+   * Actualiza las propiedades del workspace actual mediante API jerárquica.
+   * El cache interno se actualiza automáticamente con los nuevos datos.
+   * Soporta identificación por nombre o ID del workspace.
+   *
+   * @param data - Datos para actualizar el workspace
+   * @param data.name - Nuevo nombre del workspace (opcional)
+   * @returns Promise con el workspace actualizado con los nuevos datos
+   *
+   * @throws {BaserowNotFoundError} Si el workspace no existe o no se puede encontrar
+   * @throws {BaserowValidationError} Si los datos proporcionados son inválidos
+   *
+   * @example Actualización por nombre
+   * ```typescript
+   * const updated = await admin.workspace('Mi Empresa').update({
+   *   name: 'Nueva Empresa S.A.'
+   * })
+   * console.log(`Workspace actualizado: ${updated.name}`)
+   * ```
+   *
+   * @example Actualización por ID
+   * ```typescript
+   * const updated = await admin.workspace(123).update({
+   *   name: 'Empresa Actualizada'
+   * })
+   * console.log(`ID: ${updated.id}, Nombre: ${updated.name}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async update(data: UpdateWorkspaceRequest): Promise<Workspace> {
+    const workspace = await this.get()
+    const contextAccess = (this.workspaceService as any)[Symbol.for('workspaceContext')]
+    const updatedWorkspace = await contextAccess.updateWorkspace(workspace.id, data)
+
+    // Actualizar cache interno
+    this.resolvedWorkspace = updatedWorkspace
+
+    if (this.logger) {
+      this.logger.info(`Workspace updated: "${updatedWorkspace.name}" (ID: ${updatedWorkspace.id})`)
+    }
+
+    return updatedWorkspace
+  }
+
+  /**
+   * Eliminar este workspace
+   *
+   * Elimina permanentemente el workspace y todas sus databases, tablas y datos asociados.
+   * Esta operación es **irreversible** y limpia automáticamente el cache interno.
+   * Soporta identificación por nombre o ID del workspace.
+   *
+   * ⚠️ **ADVERTENCIA**: Esta operación elimina todo el contenido del workspace:
+   * - Todas las databases del workspace
+   * - Todas las tablas y campos de esas databases
+   * - Todos los datos (filas) almacenados
+   * - Todos los database tokens asociados
+   *
+   * @returns Promise que resuelve cuando el workspace es completamente eliminado
+   *
+   * @throws {BaserowNotFoundError} Si el workspace no existe o no se puede encontrar
+   * @throws {BaserowAuthError} Si no tienes permisos para eliminar el workspace
+   *
+   * @example Eliminación por nombre
+   * ```typescript
+   * // Eliminar workspace identificado por nombre
+   * await admin.workspace('Mi Empresa').delete()
+   * console.log('Workspace "Mi Empresa" eliminado exitosamente')
+   * ```
+   *
+   * @example Eliminación por ID
+   * ```typescript
+   * // Eliminar workspace identificado por ID numérico
+   * await admin.workspace(123).delete()
+   * console.log('Workspace con ID 123 eliminado exitosamente')
+   * ```
+   *
+   * @example Patrón de confirmación seguro
+   * ```typescript
+   * const workspaceName = 'Empresa Temporal'
+   * const workspace = await admin.workspace(workspaceName).get()
+   *
+   * console.log(`¿Seguro que quieres eliminar "${workspace.name}"?`)
+   * console.log(`Contiene ${workspace.databases?.length || 0} databases`)
+   *
+   * // Confirmar antes de eliminar
+   * if (confirmDeletion) {
+   *   await admin.workspace(workspaceName).delete()
+   *   console.log('Workspace eliminado exitosamente')
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async delete(): Promise<void> {
+    const workspace = await this.get()
+    const contextAccess = (this.workspaceService as any)[Symbol.for('workspaceContext')]
+    await contextAccess.deleteWorkspace(workspace.id)
+
+    if (this.logger) {
+      this.logger.info(`Workspace deleted: "${workspace.name}" (ID: ${workspace.id})`)
+    }
+
+    // Limpiar cache
+    this.resolvedWorkspace = undefined
+  }
+
+  /**
+   * Obtener este workspace completo
+   *
+   * Recupera el workspace con todos sus datos y metadatos.
+   * Utiliza lazy loading con cache para evitar resoluciones repetidas.
+   * Soporta identificación por nombre o ID del workspace.
+   *
+   * @returns Promise con el workspace completo
+   *
+   * @throws {BaserowNotFoundError} Si el workspace no existe
+   * @throws {BaserowValidationError} Si el identificador es inválido
+   *
+   * @example Obtener por nombre
+   * ```typescript
+   * const workspace = await admin.workspace('Mi Empresa').get()
+   * console.log(`Workspace: ${workspace.name} (ID: ${workspace.id})`)
+   * console.log(`Creado: ${workspace.created_on}`)
+   * ```
+   *
+   * @example Obtener por ID
+   * ```typescript
+   * const workspace = await admin.workspace(123).get()
+   * console.log(`Nombre: ${workspace.name}`)
+   * console.log(`Usuarios: ${workspace.users?.length || 0}`)
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async get(): Promise<Workspace> {
+    if (this.resolvedWorkspace) {
+      return this.resolvedWorkspace
+    }
+
+    // Usar findUnique que maneja tanto ID como nombre
+    const workspace = await this.workspaceService.findUnique(this.workspaceIdentifier)
+
+    if (!workspace) {
+      throw new BaserowNotFoundError('Workspace', this.workspaceIdentifier)
+    }
+
+    this.resolvedWorkspace = workspace
+
+    if (this.logger) {
+      this.logger.info(`Retrieved workspace: "${workspace.name}" (ID: ${workspace.id})`)
+    }
+
+    return workspace
+  }
+
+  /**
+   * Verificar si este workspace existe
+   *
+   * Método de utilidad para verificar la existencia del workspace
+   * sin cargar todos sus datos. Útil para validaciones previas.
+   *
+   * @returns Promise con true si existe, false si no
+   *
+   * @example Verificar existencia por nombre
+   * ```typescript
+   * const exists = await admin.workspace('Mi Empresa').exists()
+   * if (exists) {
+   *   console.log('El workspace existe')
+   * } else {
+   *   console.log('El workspace no fue encontrado')
+   * }
+   * ```
+   *
+   * @example Verificar antes de crear
+   * ```typescript
+   * const workspaceName = 'Nueva Empresa'
+   * const exists = await admin.workspace(workspaceName).exists()
+   *
+   * if (!exists) {
+   *   await admin.workspaces.create({ name: workspaceName })
+   *   console.log('Workspace creado exitosamente')
+   * } else {
+   *   console.log('El workspace ya existe')
+   * }
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async exists(): Promise<boolean> {
+    try {
+      await this.get()
+      return true
+    } catch (error) {
+      if ((error as any).name === 'BaserowNotFoundError') {
+        return false
+      }
+      throw error
+    }
+  }
+}