@gzl10/baserow 1.2.0

package/src/types/fields.ts

@@ -0,0 +1,456 @@
+/**
+ * Tipos relacionados con campos (fields) de Baserow
+ */
+
+/**
+ * Tipo de campo de Baserow (21/22 tipos soportados - 95% cobertura)
+ *
+ * @aiContext Usa este tipo para entender los campos disponibles y sus propósitos
+ *
+ * @aiMapping Mapeo de tipos de campo a casos de uso:
+ *
+ * **Campos de Texto:**
+ * - `text` → String corto (máx 255 chars) - nombres, títulos, códigos
+ * - `long_text` → String largo multiline - descripciones, notas, comentarios
+ * - `url` → URLs con validación automática - sitios web, enlaces
+ * - `email` → Emails con validación automática - contactos
+ * - `phone_number` → Teléfonos con formato - contacto telefónico
+ *
+ * **Campos Numéricos:**
+ * - `number` → Números con decimales configurables (0-10) - precios, cantidades
+ * - `rating` → Estrellas/hearts/thumbs (1-10 max) - valoraciones, puntuaciones
+ * - `boolean` → True/false - checkboxes, estados binarios
+ *
+ * **Campos de Fecha/Auditoría:**
+ * - `date` → Fechas con timezone y formato - eventos, deadlines
+ * - `last_modified` → Timestamp automático última modificación (read-only)
+ * - `last_modified_by` → Usuario última modificación (read-only)
+ * - `created_on` → Timestamp creación (read-only)
+ * - `created_by` → Usuario creación (read-only)
+ *
+ * **Campos de Selección:**
+ * - `single_select` → Dropdown opciones predefinidas - status, categorías
+ * - `multiple_select` → Tags/chips múltiples opciones - etiquetas, skills
+ *
+ * **Campos Relacionales:**
+ * - `link_row` → Relaciones entre tablas (1:N, N:M) - foreign keys
+ * - `formula` → Cálculos dinámicos basados en otros campos - computed values
+ *
+ * **Campos Avanzados (v1.1.0+):**
+ * - `file` → Uploads archivos/imágenes - documentos, fotos
+ * - `count` → Contador automático filas relacionadas - total items
+ * - `rollup` → Agregaciones (sum, avg, min, max) de relacionados - totales
+ * - `lookup` → Buscar valores de tablas relacionadas - referencias
+ * - `autonumber` → ID auto-incremental único - tickets, facturas
+ *
+ * **No Soportado:**
+ * - `multiple_collaborators` → ❌ Pendiente implementación
+ *
+ * @see {@link https://baserow.io/docs/apis/field-types|Baserow Field Types Docs}
+ *
+ * @example Crear diferentes tipos de campos
+ * ```typescript
+ * // Campos básicos
+ * await table.field.createText('full_name')
+ * await table.field.createEmail('contact')
+ * await table.field.createLongText('description')
+ *
+ * // Campos numéricos
+ * await table.field.createNumber('price', 2) // 2 decimales
+ * await table.field.createRating('satisfaction', 5, 'star') // 1-5 estrellas
+ * await table.field.createBoolean('is_active')
+ *
+ * // Campos de fecha
+ * await table.field.createDate('birthday')
+ *
+ * // Campos de selección
+ * await table.field.createSingleSelect('status', [
+ *   { value: 'pending', color: 'yellow' },
+ *   { value: 'completed', color: 'green' }
+ * ])
+ *
+ * // Campos relacionales
+ * await table.field.createLinkRow('customer', customersTableId)
+ * await table.field.createFormula('total', 'field("quantity") * field("price")')
+ *
+ * // Campos avanzados (v1.1.0+)
+ * await table.field.createFile('documents')
+ * await table.field.createCount('total_orders', ordersTableId)
+ * await table.field.createRollup('revenue', ordersTableId, priceFieldId, 'sum')
+ * await table.field.createLookup('customer_name', ordersTableId, nameFieldId)
+ * await table.field.createAutonumber('ticket_id')
+ * ```
+ *
+ * @since 1.0.0
+ */
+export type FieldType =
+  | 'text'
+  | 'long_text'
+  | 'url'
+  | 'email'
+  | 'phone_number'
+  | 'number'
+  | 'rating'
+  | 'boolean'
+  | 'date'
+  | 'last_modified'
+  | 'last_modified_by'
+  | 'created_on'
+  | 'created_by'
+  | 'single_select'
+  | 'multiple_select'
+  | 'file'
+  | 'multiple_collaborators'
+  | 'link_row'
+  | 'count'
+  | 'rollup'
+  | 'lookup'
+  | 'formula'
+  | 'autonumber'
+
+export type NumberSeparator = '' | 'SPACE_COMMA' | 'SPACE_PERIOD' | 'COMMA_PERIOD' | 'PERIOD_COMMA'
+
+export type RatingStyle = 'star' | 'heart' | 'thumbs-up' | 'flag' | 'smile'
+
+export type RatingColor =
+  // Colores básicos
+  | 'red'
+  | 'blue'
+  | 'green'
+  | 'yellow'
+  | 'orange'
+  | 'purple'
+  // Variantes claras
+  | 'light-red'
+  | 'light-blue'
+  | 'light-green'
+  | 'light-yellow'
+  | 'light-orange'
+  | 'light-purple'
+  // Variantes oscuras
+  | 'dark-red'
+  | 'dark-blue'
+  | 'dark-green'
+  | 'dark-yellow'
+  | 'dark-orange'
+  | 'dark-purple'
+  // Escala de grises
+  | 'gray'
+  | 'light-gray'
+  | 'dark-gray'
+  // Extremos
+  | 'black'
+  | 'white'
+
+/**
+ * Tipos de restricciones de valor para campos
+ * Introducidos en Baserow v1.35+
+ *
+ * @since 1.1.0
+ */
+export type ConstraintType =
+  | 'unique' // Valores únicos, excluyendo vacíos
+  | 'unique_with_empty' // Valores únicos, incluyendo vacíos
+
+/**
+ * Configuración de restricción de campo
+ *
+ * @since 1.1.0
+ */
+export interface FieldConstraint {
+  type: ConstraintType
+  active: boolean
+}
+
+/**
+ * Opciones avanzadas de campo (v1.35+)
+ * Incluye configuración de índices y restricciones
+ *
+ * @since 1.1.0
+ */
+export interface FieldAdvancedOptions {
+  /** Habilitar índice para performance mejorada en filtros */
+  index?: boolean
+  /** Restricciones de valor para integridad de datos */
+  constraints?: FieldConstraint[]
+}
+
+export interface SelectOption {
+  id?: number
+  value: string
+  color: string
+}
+
+export interface Field {
+  id: number
+  table_id: number
+  name: string
+  order: number
+  type: FieldType
+  primary: boolean
+  read_only: boolean
+  description?: string
+
+  // Propiedades específicas por tipo
+  select_options?: SelectOption[]
+  link_row_table_id?: number
+  link_row_related_field_id?: number
+  number_decimal_places?: number
+  number_negative?: boolean
+  number_prefix?: string
+  number_suffix?: string
+  number_separator?: NumberSeparator
+  date_format?: string
+  date_include_time?: boolean
+  date_time_format?: string
+  date_show_tzinfo?: boolean
+  date_force_timezone?: string
+  date_force_timezone_offset?: number
+  max_value?: number
+  color?: RatingColor
+  style?: RatingStyle
+  formula?: string
+  formula_type?: string
+  text_default?: string
+  number_default?: string
+  boolean_default?: boolean
+  date_default?: string
+
+  // Funcionalidades avanzadas (v1.35+)
+  /** Indica si el campo tiene índice habilitado para performance */
+  index?: boolean
+  /** Restricciones de valor activas en el campo */
+  constraints?: FieldConstraint[]
+}
+
+export interface CreateFieldRequest {
+  name: string
+  type: FieldType
+  description?: string
+
+  // Opciones específicas por tipo
+  select_options?: SelectOption[]
+  link_row_table_id?: number
+  target_field_id?: number
+  through_field_id?: number
+  rollup_function?: string
+  number_decimal_places?: number
+  number_negative?: boolean
+  number_prefix?: string
+  number_suffix?: string
+  number_separator?: NumberSeparator
+  date_format?: string
+  date_include_time?: boolean
+  date_time_format?: string
+  date_show_tzinfo?: boolean
+  date_force_timezone?: string
+  date_force_timezone_offset?: number
+  max_value?: number
+  color?: RatingColor
+  style?: RatingStyle
+  formula?: string
+  text_default?: string
+  number_default?: string | null
+  boolean_default?: boolean
+  date_default?: string
+
+  // Funcionalidades avanzadas (v1.35+)
+  /** Habilitar índice para performance mejorada en filtros */
+  index?: boolean
+  /** Restricciones de valor para integridad de datos */
+  constraints?: FieldConstraint[]
+}
+
+export interface UpdateFieldRequest extends Partial<CreateFieldRequest> {
+  name?: string
+}
+
+// ===== TIPOS CONDICIONALES PARA FIELDS.CREATE() =====
+
+/**
+ * Tipo base para creación de campos con propiedades comunes
+ */
+interface BaseFieldCreate {
+  name: string
+  description?: string
+  index?: boolean
+  constraints?: FieldConstraint[]
+}
+
+/**
+ * Tipos específicos para cada tipo de campo
+ * Proporcionan type safety y autocompletado contextual
+ */
+interface TextFieldCreate extends BaseFieldCreate {
+  type: 'text'
+  text_default?: string
+}
+
+interface LongTextFieldCreate extends BaseFieldCreate {
+  type: 'long_text'
+  text_default?: string
+}
+
+interface UrlFieldCreate extends BaseFieldCreate {
+  type: 'url'
+}
+
+interface EmailFieldCreate extends BaseFieldCreate {
+  type: 'email'
+}
+
+interface PhoneNumberFieldCreate extends BaseFieldCreate {
+  type: 'phone_number'
+  text_default?: string
+}
+
+interface NumberFieldCreate extends BaseFieldCreate {
+  type: 'number'
+  number_decimal_places?: number
+  number_negative?: boolean
+  number_prefix?: string
+  number_suffix?: string
+  number_separator?: NumberSeparator
+  number_default?: string | null
+}
+
+interface BooleanFieldCreate extends BaseFieldCreate {
+  type: 'boolean'
+  boolean_default?: boolean
+}
+
+interface RatingFieldCreate extends BaseFieldCreate {
+  type: 'rating'
+  max_value?: number
+  color?: RatingColor
+  style?: RatingStyle
+}
+
+interface DateFieldCreate extends BaseFieldCreate {
+  type: 'date'
+  date_format?: string
+  date_include_time?: boolean
+  date_time_format?: string
+  date_show_tzinfo?: boolean
+  date_force_timezone?: string
+  date_force_timezone_offset?: number
+  date_default?: string
+}
+
+interface SingleSelectFieldCreate extends BaseFieldCreate {
+  type: 'single_select'
+  select_options?: SelectOption[]
+}
+
+interface MultipleSelectFieldCreate extends BaseFieldCreate {
+  type: 'multiple_select'
+  select_options?: SelectOption[]
+}
+
+interface LinkRowFieldCreate extends BaseFieldCreate {
+  type: 'link_row'
+  link_row_table_id: number
+}
+
+interface FormulaFieldCreate extends BaseFieldCreate {
+  type: 'formula'
+  formula: string
+}
+
+interface FileFieldCreate extends BaseFieldCreate {
+  type: 'file'
+}
+
+interface AutonumberFieldCreate extends BaseFieldCreate {
+  type: 'autonumber'
+}
+
+interface CountFieldCreate extends BaseFieldCreate {
+  type: 'count'
+  through_field_id: number
+}
+
+interface RollupFieldCreate extends BaseFieldCreate {
+  type: 'rollup'
+  through_field_id: number
+  target_field_id: number
+  rollup_function?: string
+}
+
+interface LookupFieldCreate extends BaseFieldCreate {
+  type: 'lookup'
+  through_field_id: number
+  target_field_id: number
+}
+
+interface LastModifiedFieldCreate extends BaseFieldCreate {
+  type: 'last_modified'
+}
+
+interface LastModifiedByFieldCreate extends BaseFieldCreate {
+  type: 'last_modified_by'
+}
+
+interface CreatedOnFieldCreate extends BaseFieldCreate {
+  type: 'created_on'
+}
+
+interface CreatedByFieldCreate extends BaseFieldCreate {
+  type: 'created_by'
+}
+
+interface MultipleCollaboratorsFieldCreate extends BaseFieldCreate {
+  type: 'multiple_collaborators'
+}
+
+/**
+ * Union type condicional que mapea cada FieldType a su interfaz específica
+ * Proporciona IntelliSense dinámico basado en el tipo seleccionado
+ */
+export type CreateFieldByType<T extends FieldType> = T extends 'text'
+  ? TextFieldCreate
+  : T extends 'long_text'
+    ? LongTextFieldCreate
+    : T extends 'url'
+      ? UrlFieldCreate
+      : T extends 'email'
+        ? EmailFieldCreate
+        : T extends 'phone_number'
+          ? PhoneNumberFieldCreate
+          : T extends 'number'
+            ? NumberFieldCreate
+            : T extends 'boolean'
+              ? BooleanFieldCreate
+              : T extends 'rating'
+                ? RatingFieldCreate
+                : T extends 'date'
+                  ? DateFieldCreate
+                  : T extends 'single_select'
+                    ? SingleSelectFieldCreate
+                    : T extends 'multiple_select'
+                      ? MultipleSelectFieldCreate
+                      : T extends 'link_row'
+                        ? LinkRowFieldCreate
+                        : T extends 'formula'
+                          ? FormulaFieldCreate
+                          : T extends 'file'
+                            ? FileFieldCreate
+                            : T extends 'autonumber'
+                              ? AutonumberFieldCreate
+                              : T extends 'count'
+                                ? CountFieldCreate
+                                : T extends 'rollup'
+                                  ? RollupFieldCreate
+                                  : T extends 'lookup'
+                                    ? LookupFieldCreate
+                                    : T extends 'last_modified'
+                                      ? LastModifiedFieldCreate
+                                      : T extends 'last_modified_by'
+                                        ? LastModifiedByFieldCreate
+                                        : T extends 'created_on'
+                                          ? CreatedOnFieldCreate
+                                          : T extends 'created_by'
+                                            ? CreatedByFieldCreate
+                                            : T extends 'multiple_collaborators'
+                                              ? MultipleCollaboratorsFieldCreate
+                                              : CreateFieldRequest // fallback genérico para tipos no mapeados

package/src/types/index.ts

@@ -0,0 +1,222 @@
+/**
+ * Sistema de tipos completo para la librería @gzl10/baserow
+ *
+ * Este archivo centraliza todos los tipos TypeScript necesarios para interactuar
+ * con la API de Baserow. Los tipos están organizados por categorías funcionales
+ * y proporcionan tipado estricto para todas las operaciones.
+ *
+ * **Categorías de tipos:**
+ * - **Core**: Entidades principales (Workspace, Database, Table, Row, Field)
+ * - **Auth**: Autenticación y configuración (JWT, Database Tokens, credenciales)
+ * - **Fields**: 21 tipos de campos con sus configuraciones específicas
+ * - **Requests**: Payloads para operaciones CREATE/UPDATE
+ * - **Responses**: Estructuras de respuesta de la API
+ * - **Errors**: Jerarquía de errores tipados con contexto
+ * - **Tokens**: Database tokens con permisos granulares
+ *
+ * **Beneficios del tipado estricto:**
+ * - IntelliSense completo en IDEs
+ * - Detección de errores en tiempo de compilación
+ * - Refactoring seguro
+ * - Documentación viva del API
+ * - Compatibilidad con herramientas de generación de tipos
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   BaserowClient,
+ *   Table,
+ *   Field,
+ *   QueryOptions,
+ *   BaserowError
+ * } from '@gzl10/baserow'
+ *
+ * // Tipos inferidos automáticamente
+ * const client = new BaserowClient({ url: '...', token: '...' })
+ * const tables: Table[] = await client.database(123).tables.findMany()
+ * const options: QueryOptions = { page: 1, size: 100, filters: { active: true } }
+ * ```
+ *
+ * @since 1.0.0
+ */
+
+/**
+ * Entidades principales y utilidades core
+ *
+ * Tipos fundamentales que representan las entidades principales
+ * de Baserow: workspaces, databases, tables, rows y usuarios.
+ *
+ * @since 1.0.0
+ */
+export type {
+  Logger,
+  UserReference,
+  Workspace,
+  Database,
+  DatabaseLight,
+  Table,
+  TableFromAllTables,
+  Row,
+  User,
+  UserProfile
+} from './core'
+
+/**
+ * Autenticación y configuración
+ *
+ * Tipos para manejar autenticación JWT, configuración de clientes
+ * y operaciones de login/logout. Incluye tanto Database Tokens
+ * como JWT tokens para diferentes niveles de acceso.
+ *
+ * @since 1.0.0
+ */
+export type {
+  BaserowCredentials,
+  BaserowConfig,
+  BaserowAdminConfig,
+  BaserowPerformanceOptions,
+  LoginRequest,
+  LoginResponse,
+  RefreshTokenRequest,
+  RefreshTokenResponse,
+  ChangePasswordRequest,
+  BaserowTokenConfig,
+  BaserowCredentialsConfig,
+  BaserowCredentialsWorkspaceConfig,
+  BaserowUnifiedConfig,
+  TokenConfig,
+  CredentialsConfig,
+  CredentialsWorkspaceConfig
+} from './auth'
+
+/**
+ * Campos y tipos de datos
+ *
+ * Definiciones completas para los 21 tipos de campos soportados
+ * por Baserow, incluyendo configuraciones específicas para cada tipo,
+ * opciones de validación y metadatos.
+ *
+ * **Tipos incluidos:**
+ * - Texto: text, long_text, url, email, phone_number
+ * - Numéricos: number, boolean, rating
+ * - Fecha: date, last_modified, created_on, etc.
+ * - Selección: single_select, multiple_select
+ * - Relacionales: link_row, formula
+ * - Avanzados: file, autonumber, count, rollup, lookup
+ * - **v1.35+**: Índices para performance y constraints para integridad
+ *
+ * @since 1.0.0
+ */
+export type {
+  FieldType,
+  NumberSeparator,
+  RatingStyle,
+  RatingColor,
+  SelectOption,
+  Field,
+  CreateFieldRequest,
+  UpdateFieldRequest,
+  ConstraintType,
+  FieldConstraint,
+  FieldAdvancedOptions,
+  CreateFieldByType
+} from './fields'
+
+/**
+ * Database Tokens y permisos
+ *
+ * Sistema de tokens para acceso granular a databases y tablas específicas.
+ * Permite configurar permisos CRUD individuales y scope limitado.
+ * Incluye utilidades para tokens de librería con prefijo 'br-lib:'.
+ *
+ * @since 1.0.0
+ */
+export type {
+  DatabaseToken,
+  DatabaseTokenPermissions,
+  CreateDatabaseTokenRequest,
+  UpdateDatabaseTokenRequest
+} from './tokens'
+export { LIBRARY_TOKEN_PREFIX } from './tokens'
+
+/**
+ * Payloads de requests
+ *
+ * Estructuras de datos para todas las operaciones CREATE y UPDATE.
+ * Incluye validación de tipos y opciones para operaciones bulk optimizadas.
+ * Cubre tablas, filas, campos, usuarios y configuraciones.
+ *
+ * @since 1.0.0
+ */
+export type {
+  CreateTableRequest,
+  UpdateTableRequest,
+  CreateRowRequest,
+  UpdateRowRequest,
+  BulkCreateRowsRequest,
+  BulkUpdateRowsRequest,
+  CreateSnapshotRequest,
+  RestoreSnapshotRequest,
+  CreateWebhookRequest,
+  UpdateWebhookRequest,
+  CreateUserRequest,
+  UpdateUserRequest,
+  EmailTestRequest,
+  QueryOptions,
+  PrismaLikeQueryOptions,
+  FieldOperators,
+  WhereClause,
+  OrderByClause,
+  SelectClause,
+  BulkOptions
+} from './requests'
+
+// Schema system types
+export type {
+  DatabaseSchema,
+  TableSchema,
+  FieldSchema,
+  RelationshipSchema,
+  FieldConfig,
+  LoadSchemaOptions,
+  LoadSchemaResult,
+  SchemaControl,
+  SchemaChange,
+  LoadSchemaStats,
+  LoadSchemaMode,
+  SchemaControlStatus
+} from './schema'
+
+/**
+ * Estructuras de respuesta
+ *
+ * Tipos para las respuestas de la API de Baserow, incluyendo
+ * paginación, metadatos y estructuras anidadas. Compatible
+ * con las diferentes versiones del API.
+ *
+ * @since 1.0.0
+ */
+export type { BaserowResponse, Snapshot, Webhook, WebhookCall, HealthCheck } from './responses'
+
+/**
+ * Sistema de errores tipados
+ *
+ * Jerarquía completa de errores personalizados con contexto específico
+ * para diferentes tipos de fallos: validación, red, timeouts, rate limiting,
+ * recursos no encontrados, etc. Facilita el manejo granular de errores.
+ *
+ * @since 1.0.0
+ */
+export {
+  BaserowError,
+  BaserowValidationError,
+  BaserowNotFoundError,
+  BaserowRateLimitError,
+  BaserowNetworkError,
+  BaserowTimeoutError,
+  BaserowConfigError,
+  BaserowWorkspaceError,
+  BaserowAuthTokenExpiredError,
+  BaserowAuthTokenInvalidError,
+  BaserowReLoginRequiredError
+} from './errors'