const task = await base44.entities.Task.create({
  title: "Complete documentation",
  status: "pending",
  dueDate: "2024-12-31"
});

const tasks = await base44.entities.Task.bulkCreate([
  { title: "Task 1", status: "pending" },
  { title: "Task 2", status: "pending" }
]);

// Obtener los primeros 10 registros, ordenados por created_date descendente (máx. 5.000 por solicitud)
const tasks = await base44.entities.Task.list(
  "-created_date",  // orden (SortField: prefijo con - para descendente)
  10,               // límite
  0                 // saltar
);

// Obtener siguiente página
const page2 = await base44.entities.Task.list("-created_date", 10, 10);

// Filtro simple
const pending = await base44.entities.Task.filter({ status: "pending" });

// Múltiples condiciones
const myPending = await base44.entities.Task.filter({
  status: "pending",
  assignedTo: userId
});

// Con orden, límite, salto (máx. 5.000 por solicitud)
const recent = await base44.entities.Task.filter(
  { status: "pending" },
  "-created_date",  // orden (SortField: prefijo con - para descendente)
  5,
  0
);

// Seleccionar campos específicos
const titles = await base44.entities.Task.filter(
  { status: "pending" },
  null,
  null,
  null,
  ["id", "title"]
);

const task = await base44.entities.Task.get("task-id-123");

// Actualización parcial - solo cambian los campos especificados
await base44.entities.Task.update("task-id-123", {
  status: "completed",
  completedAt: new Date().toISOString()
});

// Registro único
const result = await base44.entities.Task.delete("task-id-123");
console.log("Deleted:", result.success);

// Varios registros que coinciden con la consulta
const manyResult = await base44.entities.Task.deleteMany({ status: "archived" });
console.log("Deleted:", manyResult.deleted);

// Actualizar todas las tareas pendientes a estado "in-progress"
const result = await base44.entities.Task.updateMany(
  { status: "pending" },                     // consulta: qué registros actualizar
  { $set: { status: "in-progress" } }        // operador de actualización de MongoDB
);
console.log("Updated:", result.updated);

// Incrementar un campo contador
await base44.entities.Task.updateMany(
  { category: "bugs" },
  { $inc: { priority: 1 } }
);

// Actualizar varios registros, cada uno con datos diferentes
const updated = await base44.entities.Task.bulkUpdate([
  { id: "task-1", status: "done", completedAt: new Date().toISOString() },
  { id: "task-2", status: "in-progress", assignedTo: userId },
  { id: "task-3", priority: 5 }
]);

// Solo frontend: importar desde CSV/archivo
const result = await base44.entities.Task.importEntities(file);
if (result.status === "success" && result.output) {
  console.log(`Imported ${result.output.length} records`);
} else {
  console.error(result.details);
}

// Suscribirse a todos los cambios en la entidad Task
const unsubscribe = base44.entities.Task.subscribe((event) => {
  console.log(`Task ${event.id} was ${event.type}:`, event.data);
  // event.type es "create", "update" o "delete"
});

// Más tarde: cancelar suscripción para dejar de recibir actualizaciones
unsubscribe();

{
  type: "create" | "update" | "delete",
  data: { ... },       // los datos de la entidad
  id: "entity-id",     // el ID de la entidad afectada
  timestamp: "2024-01-15T10:30:00Z"
}

// Obtener el registro del usuario actual
const me = await base44.entities.User.get(currentUserId);

// Rol de servicio: obtener cualquier usuario
const anyUser = await base44.asServiceRole.entities.User.get(userId);

// Solo backend
const allTasks = await base44.asServiceRole.entities.Task.list();
const allUsers = await base44.asServiceRole.entities.User.list();

/** Tipos de eventos para actualizaciones de entidad en tiempo real. */
type RealtimeEventType = "create" | "update" | "delete";

/** Carga útil recibida cuando ocurre un evento en tiempo real. */
interface RealtimeEvent<T = any> {
  /** El tipo de cambio que ocurrió. */
  type: RealtimeEventType;
  /** Los datos de la entidad. */
  data: T;
  /** El identificador único de la entidad afectada. */
  id: string;
  /** Marca de tiempo ISO 8601 de cuándo ocurrió el evento. */
  timestamp: string;
}

/** Función de callback invocada cuando ocurre un evento en tiempo real. */
type RealtimeCallback<T = any> = (event: RealtimeEvent<T>) => void;

/** Resultado devuelto al actualizar varias entidades. */
interface UpdateManyResult {
  /** Si la actualización fue exitosa. */
  success: boolean;
  /** Número de entidades que se actualizaron. */
  updated: number;
}

/** Resultado devuelto al eliminar una sola entidad. */
interface DeleteResult {
  /** Si la eliminación fue exitosa. */
  success: boolean;
}

/** Resultado devuelto al eliminar varias entidades. */
interface DeleteManyResult {
  /** Si la eliminación fue exitosa. */
  success: boolean;
  /** Número de entidades que se eliminaron. */
  deleted: number;
}

/** Resultado devuelto al importar entidades desde un archivo. */
interface ImportResult<T = any> {
  /** Estado de la operación de importación. */
  status: "success" | "error";
  /** Mensaje de detalles, por ejemplo, "Successfully imported 3 entities with RLS enforcement". */
  details: string | null;
  /** Array de objetos de entidad creados cuando tiene éxito, o null en error. */
  output: T[] | null;
}

/**
 * Tipo de campo de ordenación para consultas de entidad.
 * Admite ordenación ascendente (sin prefijo o '+') y descendente ('-').
 * Ejemplo: 'created_date', '+created_date', '-created_date'
 */
type SortField<T> = (keyof T & string) | `+${keyof T & string}` | `-${keyof T & string}`;

/** Campos añadidos por el servidor a cada registro de entidad. */
interface ServerEntityFields {
  id: string;
  created_date: string;
  updated_date: string;
  created_by?: string | null;
  created_by_id?: string | null;
  is_sample?: boolean;
}

/**
 * Registro que mapea nombres de entidad a sus tipos TypeScript.
 * Aumenta esta interfaz con tu esquema de entidad (solo campos definidos por el usuario).
 * Normalmente lo rellena el generador de tipos de la CLI de Base44.
 */
interface EntityTypeRegistry {}

/**
 * Tipo de registro completo para cada entidad: campos de esquema + campos inyectados por el servidor.
 */
type EntityRecord = {
  [K in keyof EntityTypeRegistry]: EntityTypeRegistry[K] & ServerEntityFields;
};

/** Manejador de entidad que proporciona operaciones CRUD para un tipo de entidad específico. */
interface EntityHandler<T = any> {
  /** Lista registros con paginación y ordenación opcionales. Máx. 5.000 por solicitud. */
  list<K extends keyof T = keyof T>(
    sort?: SortField<T>,
    limit?: number,
    skip?: number,
    fields?: K[]
  ): Promise<Pick<T, K>[]>;

  /** Filtra registros basados en una consulta. Máx. 5.000 por solicitud. */
  filter<K extends keyof T = keyof T>(
    query: Partial<T>,
    sort?: SortField<T>,
    limit?: number,
    skip?: number,
    fields?: K[]
  ): Promise<Pick<T, K>[]>;

  /** Obtiene un solo registro por ID. */
  get(id: string): Promise<T>;

  /** Crea un nuevo registro. */
  create(data: Partial<T>): Promise<T>;

  /** Actualiza un registro existente. */
  update(id: string, data: Partial<T>): Promise<T>;

  /** Elimina un solo registro por ID. */
  delete(id: string): Promise<DeleteResult>;

  /** Elimina varios registros que coinciden con una consulta. */
  deleteMany(query: Partial<T>): Promise<DeleteManyResult>;

  /** Crea varios registros en una sola solicitud. */
  bulkCreate(data: Partial<T>[]): Promise<T[]>;

  /**
   * Actualiza varios registros que coinciden con una consulta usando operadores de actualización de MongoDB.
   * @param query - Filtro para seleccionar qué registros actualizar.
   * @param data - Objeto de operador de actualización de MongoDB (por ejemplo, `{ $set: { field: value } }`).
   */
  updateMany(query: Partial<T>, data: Record<string, Record<string, any>>): Promise<UpdateManyResult>;

  /** Actualiza varios registros por ID, cada uno con sus propios datos de actualización. */
  bulkUpdate(data: (Partial<T> & { id: string })[]): Promise<T[]>;

  /** Importa registros desde un archivo (solo frontend). */
  importEntities(file: File): Promise<ImportResult<T>>;

  /** Suscribe a actualizaciones en tiempo real. Devuelve una función de cancelación de suscripción. */
  subscribe(callback: RealtimeCallback<T>): () => void;
}

/** Módulo Entities: las claves de registro tipadas obtienen manejadores tipados; el acceso dinámico permanece sin tipar. */
type EntitiesModule = TypedEntitiesModule & DynamicEntitiesModule;

type TypedEntitiesModule = {
  [K in keyof EntityTypeRegistry]: EntityHandler<EntityRecord[K]>;
};

type DynamicEntitiesModule = {
  [entityName: string]: EntityHandler<any>;
};