Documentation 35 min read

Easy PocketBase Manager

Published: April 16, 2025 Last Updated: June 1, 2025

Introdução

O Easy PocketBase Manager (v1.0-2) é uma biblioteca JavaScript robusta projetada para simplificar a interação com o PocketBase. Ele fornece uma interface unificada para realizar operações de autenticação, gerenciamento de dados, manipulação de arquivos, controle de roles e muito mais. Além disso, o Easy PocketBase Manager incorpora funcionalidades avançadas como gerenciamento de eventos personalizados, análise de operações realizadas, cache de dados utilizando o IndexedDB e persistência de dados, restauração automática de sessão via cookies do navegador, verificação de saúde do servidor PocketBase, mecanismo de repetição (retry) para operações de rede e opções avançadas de requisição.

Principais funcionalidades do Easy PocketBase Manager:

  • Gerenciamento de autenticação de usuários (login, signup, logout, logoutAndClear, verificação de email, recuperação de senha, restauração automática de sessão via cookie).
  • Operações CRUD (Create, Read, Update, Delete) simplificadas para coleções do PocketBase.
  • Operações em lote para criação, atualização e exclusão de múltiplos registros.
  • Manipulação de arquivos, incluindo upload de um ou múltiplos arquivos e download.
  • Gerenciamento de roles e permissões de usuários.
  • Emissão e escuta de eventos personalizados para monitorar ações específicas.
  • Análise detalhada das operações realizadas e uso de recursos.
  • Exportação e importação de dados em formato JSON, CSV e XML para facilitar migrações e backups.
  • Sincronização de dados entre diferentes instâncias do PocketBaseManager.
  • Cache de dados utilizando IndexedDB para melhorar o desempenho e reduzir a necessidade de requisições ao servidor.
  • Persistência de dados como logs de auditoria, sessões e análises utilizando IndexedDB.
  • Verificação de saúde do servidor PocketBase.
  • Facilidade de integração com projetos existentes graças a uma API intuitiva e documentação detalhada.
  • Mecanismo de repetição (retry) para operações de rede, aumentando a robustez.
  • Opções avançadas de requisição por método (methodRequestOptions) e globais (defaultRequestOptions, disableAutoCancellation).
  • Leitura de registros e listas com atualização automática em tempo real.

Características Principais

  • Gerenciamento de Autenticação: Facilita o processo de login, signup, logout, logoutAndClear, verificação de email e recuperação de senha. Inclui restauração automática de sessão.
  • Operações CRUD Simplificadas: Métodos intuitivos para criar, ler, atualizar e deletar registros em coleções do PocketBase.
  • Operações em Lote: Suporte para criação, atualização e exclusão de múltiplos registros de uma só vez, otimizando o desempenho.
  • Manipulação de Arquivos: Upload de um ou múltiplos arquivos e download de arquivos associados a registros, com gerenciamento eficiente de armazenamento.
  • Gerenciamento de Roles: Atribuição e recuperação de roles para usuários, permitindo controle granular de permissões.
  • Eventos Personalizados: Emissão de eventos como 'auth', 'signup', 'create', 'update', 'delete', 'list', 'batchCreate', 'batchUpdate', 'batchDelete', 'fileUploaded', 'roleAssigned', 'rolesFetched', 'import', 'syncCompleted', entre outros, permitindo integração com outras partes da aplicação.
  • Análise de Operações: Monitoramento de operações realizadas, incluindo contagem de operações e uso de bytes.
  • Exportação e Importação de Dados: Métodos para exportar dados para JSON, CSV e XML e importar dados a partir desses formatos, facilitando backups e migrações.
  • Sincronização de Dados: Sincronização de dados entre diferentes instâncias do PocketBaseManager e sincronização periódica do cache com o servidor.
  • Cache de Dados: Utiliza o IndexedDB para armazenar registros em cache, melhorando o desempenho e reduzindo a necessidade de requisições frequentes ao servidor.
  • Persistência de Dados: Armazena logs de auditoria, sessões e análises utilizando IndexedDB para garantir a persistência dos dados.
  • Verificação de Saúde: Método para verificar rapidamente a disponibilidade e o status do servidor PocketBase.
  • Robustez Aprimorada: Inclui mecanismo de repetição (retry) para operações de rede.
  • Controle Avançado de Requisições: Permite configurar opções de requisição globais e por método.
  • Leitura com Atualização Automática: Métodos para ler registros e listas com atualização automática de dados via eventos em tempo real.
  • Facilidade de Integração: API intuitiva e documentação detalhada que facilitam a integração com projetos existentes.

Instalação

Para instalar o Easy PocketBase Manager, siga os passos abaixo:

Passo a Passo
  • Inclua o Script do PocketBase: Adicione o script do PocketBase no seu HTML antes do fechamento da tag </body>:
<script src="https://cdnjs.cloudflare.com/ajax/libs/pocketbase/0.25.0/pocketbase.umd.js"></script>
  • Inclua o Script do PocketBase Manager: Adicione o script do PocketBase Manager após o script do PocketBase:
<script src="https://cdn.alphasystem.dev/plugins/easy-pocketbase-manager/latest/script-min.js"></script>
  • Inicialização Básica: Inicialize o PocketBase Manager com as configurações padrão:
// Inicializa o PocketBase Manager com as configurações padrão
// Certifique-se de que 'PocketBase' foi carregado antes (via script do PocketBase)

const pbManager = new PocketBaseManager({
  baseUrl: 'http://127.0.0.1:8090', // URL base do PocketBase
  collection: 'users' // Coleção padrão a ser utilizada (opcional, default: null)
});
  • Configuração Avançada (Opcional): Personalize as opções conforme necessário:
// Exemplo de configuração avançada
// A classe PocketBaseManager se encarrega de instanciar o PocketBase internamente.

const pbManager = new PocketBaseManager({
  baseUrl: 'https://meuservidor.com',
  collection: 'clientes',
  cacheEnabled: true, // Habilita o cache de dados (IndexedDB)
  cacheExpirationMinutes: 120, // Define a expiração do cache para 120 minutos
  syncIntervalMinutes: 15, // Define o intervalo de sincronização para 15 minutos
  persistenceEnabled: true, // Habilita a persistência de dados
  maxAuditLogs: 500, // Define o número máximo de logs de auditoria
  disableAutoCancellation: true, // Desabilita o cancelamento automático de requisições
  defaultRequestOptions: { wichtigenough: true } // Opções padrão para todas as requisições
  // Outras opções de configuração podem ser adicionadas conforme necessário
});

Configuração

O Easy PocketBase Manager oferece várias opções de configuração para personalizar seu comportamento e funcionalidades. As configurações padrão podem ser sobrescritas pelo usuário através do objeto de opções passado na inicialização do PocketBaseManager. A seguir, detalhamos as principais opções disponíveis:

  • baseUrl: (String) URL base do servidor PocketBase. Padrão: 'http://127.0.0.1:8090'.
  • collection: (String) Nome da coleção padrão a ser utilizada nas operações CRUD. Padrão: null.
  • cacheEnabled: (Boolean) Habilita ou desabilita o cache de dados utilizando IndexedDB. Padrão: true.
  • cacheExpirationMinutes: (Number) Define o tempo de expiração do cache em minutos. Padrão: 60.
  • syncIntervalMinutes: (Number) Define o intervalo de sincronização de dados em minutos. Padrão: 10.
  • persistenceEnabled: (Boolean) Habilita ou desabilita a persistência de dados (logs de auditoria, sessões e análises) utilizando IndexedDB. Padrão: true.
  • disableAutoCancellation: (Boolean) Se true, desabilita o cancelamento automático de requisições do PocketBase (útil para requisições de longa duração, definindo $autoCancel como false nas requisições). Padrão: false (auto-cancelamento habilitado por padrão pelo PocketBase SDK).
  • defaultRequestOptions: (Object) Opções padrão a serem passadas para todas as requisições ao PocketBase SDK. Padrão: {}.
  • maxAuditLogs: (Number) Número máximo de logs de auditoria a serem mantidos. Padrão: 1000.

Nota: Certifique-se de que o servidor PocketBase está corretamente configurado e acessível através da baseUrl fornecida. Também verifique se o script do PocketBase (pocketbase.umd.js) foi incluído antes do Easy PocketBase Manager.

Exemplo de configuração personalizada:

// Exemplo de configuração personalizada
const pbManager = new PocketBaseManager({
  baseUrl: 'https://meuservidor.com',
  collection: 'clientes',
  cacheEnabled: true,        // Habilita o cache
  cacheExpirationMinutes: 120, // Expira o cache após 120 minutos
  syncIntervalMinutes: 15,  // Sincronização periódica de 15 em 15 minutos
  persistenceEnabled: true,  // Habilita persistência de logs, sessões e análises via IndexedDB
  maxAuditLogs: 500,
  disableAutoCancellation: false
});

Uso e Integração

Após a instalação e configuração, o Easy PocketBase Manager estará pronto para uso. A seguir, descrevemos como interagir com o sistema e integrar as funcionalidades do PocketBase no fluxo da sua aplicação:

  • Autenticação de Usuários: Utilize os métodos login, signup, logout, logoutAndClear, sendPasswordResetEmail e verifyEmail para gerenciar a autenticação de usuários. O gerenciador também tentará restaurar automaticamente uma sessão existente via cookies na inicialização. O método 'login' é usado para autenticação explícita com email/senha.
  • Operações CRUD: Utilize os métodos create, read, update, delete para gerenciar registros nas coleções do PocketBase.
  • Operações em Lote: Utilize os métodos batchCreate, batchUpdate, batchDelete para realizar operações em múltiplos registros simultaneamente.
  • Manipulação de Arquivos: Utilize os métodos uploadFile, uploadMultipleFiles, downloadFile, deleteFile, getFileUrl e getMultipleFileUrls para gerenciar arquivos associados a registros.
  • Gerenciamento de Roles: Utilize os métodos assignRole e getRoles para controlar as permissões de usuários.
  • Eventos: Escute eventos como 'auth', 'signup', 'passwordResetRequested', 'emailVerified', 'create', 'read', 'update', 'delete', 'list', 'batchCreate', 'batchUpdate', 'batchDelete', 'fileUploaded', 'fileDeleted', 'increment', 'decrement', 'roleAssigned', 'rolesFetched', 'import', 'syncCompleted', entre outros, para reagir a ações específicas na aplicação. Você pode utilizar on, once, removeListener e emit para manipular eventos locais.
  • Exportação e Importação de Dados: Utilize os métodos exportToJSON, importFromJSON, exportToCSV, importFromCSV, exportToXML, importFromXML para exportar e importar dados em formatos JSON, CSV e XML.
  • Sincronização de Dados: Utilize o método sync para sincronizar dados entre diferentes instâncias do PocketBaseManager. Você também pode iniciar e parar a sincronização periódica com startSync e stopSync.
  • Cache de Dados: Utilize os métodos clearCache, invalidateRecord para gerenciar o cache de dados.
  • Leitura com Atualização Automática: Utilize os métodos readWithAutoUpdate e listWithAutoUpdate para ler registros com atualização automática de dados (assinando eventos em tempo real).
  • Análise de Operações: Utilize os métodos getAnalytics, resetAnalytics, exportAnalytics para obter e gerenciar estatísticas sobre as operações realizadas.
  • Gerenciamento de Sessões: Utilize os métodos getSessions, endSession, updateSessionActivity, deleteSession, clearSessions, exportSessions para gerenciar sessões de usuários.
  • Gerenciamento de Logs de Auditoria: Utilize os métodos getAuditLogs, deleteAuditLog, clearAuditLogs, exportAuditLogs para gerenciar logs de auditoria.
  • Métodos Adicionais: Utilize os métodos cloneRecord, countRecords, searchRecords, increment, decrement, downloadAsJSON, downloadAsCSV e downloadAsXML para funcionalidades avançadas de manipulação de dados.
  • Configuração da Coleção Padrão: Utilize o método setDefaultCollection para definir a coleção padrão para as operações.
  • Opções de Requisição: Muitos métodos aceitam um parâmetro methodRequestOptions para passar opções específicas para a requisição do PocketBase SDK (ex: { $autoCancel: false }).

Exemplo de uso básico:

Autenticação de Usuário

// Realiza login de um usuário
pbManager.login('usuario@exemplo.com', 'senha_segura')
  .then((authData) => {
    console.log('Usuário autenticado:', authData);
  })
  .catch((error) => {
    console.error('Erro ao autenticar usuário:', error);
  });

Criação de um Registro

// Cria um novo registro na coleção padrão
pbManager.create({ nome: 'João', idade: 30 })
  .then((registro) => {
    console.log('Registro criado:', registro);
  })
  .catch((error) => {
    console.error('Erro ao criar registro:', error);
  });

Leitura de um Registro

// Lê um registro pelo ID na coleção padrão
pbManager.read('registroId123')
  .then((registro) => {
    console.log('Registro encontrado:', registro);
  })
  .catch((error) => {
    console.error('Erro ao ler registro:', error);
  });

Leitura com Atualização Automática

// Lê um registro e atualiza automaticamente quando há novas informações
pbManager.readWithAutoUpdate('registroId123', 'clientes', (registroAtualizado) => {
  console.log('Registro atualizado automaticamente:', registroAtualizado);
})
.then(({ initialData, unsubscribe }) => {
  console.log('Dados iniciais:', initialData);
  // Guarde a função unsubscribe para usá-la depois, se necessário
  // ex: setTimeout(() => unsubscribe(), 60000);
})
.catch(error => console.error('Erro em readWithAutoUpdate:', error));

Leitura de Lista com Atualização Automática

// Lê uma lista de registros e atualiza automaticamente quando há novas informações
pbManager.listWithAutoUpdate({ page: 1, perPage: 10, filter: 'idade > 25' }, 'clientes', (registrosAtualizados) => {
  console.log('Lista de registros atualizada automaticamente:', registrosAtualizados);
})
.then(({ initialRecords, unsubscribe }) => {
  console.log('Registros iniciais:', initialRecords);
  // Guarde a função unsubscribe para usá-la depois, se necessário
})
.catch(error => console.error('Erro em listWithAutoUpdate:', error));

Atualização de um Registro

// Atualiza um registro pelo ID na coleção padrão
pbManager.update('registroId123', { idade: 31 })
  .then((registroAtualizado) => {
    console.log('Registro atualizado:', registroAtualizado);
  })
  .catch((error) => {
    console.error('Erro ao atualizar registro:', error);
  });

Deleção de um Registro

// Deleta um registro pelo ID na coleção padrão
pbManager.delete('registroId123')
  .then((response) => {
    console.log('Registro deletado:', response);
  })
  .catch((error) => {
    console.error('Erro ao deletar registro:', error);
  });

Logout e Limpeza de Dados

// Realiza logout e limpa todos os dados persistidos
pbManager.logoutAndClear()
  .then(() => {
    console.log('Usuário desautenticado e dados limpos com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao desautenticar e limpar dados:', error);
  });

Operações em Lote

// Cria múltiplos registros em lote
const novosRegistros = [
  { nome: 'Mariana', email: 'mariana@exemplo.com', idade: 22 },
  { nome: 'Felipe', email: 'felipe@exemplo.com', idade: 29 }
];

pbManager.batchCreate(novosRegistros)
  .then((registrosCriados) => {
    console.log('Registros criados em lote:', registrosCriados);
  })
  .catch((error) => {
    console.error('Erro ao criar registros em lote:', error);
  });

// Atualiza múltiplos registros em lote
const atualizacoes = {
  'registroId1': { idade: 23 },
  'registroId2': { idade: 30 }
};

pbManager.batchUpdate(atualizacoes)
  .then((registrosAtualizados) => {
    console.log('Registros atualizados em lote:', registrosAtualizados);
  })
  .catch((error) => {
    console.error('Erro ao atualizar registros em lote:', error);
  });

// Deleta múltiplos registros em lote
const idsParaDeletar = ['registroId1', 'registroId2'];

pbManager.batchDelete(idsParaDeletar)
  .then((respostas) => {
    console.log('Registros deletados em lote:', respostas);
  })
  .catch((error) => {
    console.error('Erro ao deletar registros em lote:', error);
  });

Manipulação de Arquivos

// Faz upload de um arquivo para um registro específico
const arquivo = document.querySelector('#inputArquivo').files[0];
const recordId = 'registroId123';
const campoArquivo = 'documento';

pbManager.uploadFile(arquivo, 'clientes', recordId, campoArquivo)
  .then(({ record, fileUrl }) => {
    console.log('Arquivo enviado:', record);
    console.log('URL do arquivo:', fileUrl);
  })
  .catch((error) => {
    console.error('Erro ao enviar arquivo:', error);
  });

// Faz upload de múltiplos arquivos para um registro específico
const arquivos = document.querySelector('#inputArquivos').files;
const recordIdMulti = 'registroId456';
const campoArquivoMulti = 'documentos';

pbManager.uploadMultipleFiles(arquivos, 'clientes', recordIdMulti, campoArquivoMulti)
  .then((resultados) => {
    console.log('Arquivos enviados (resultados):', resultados);
  })
  .catch((error) => {
    console.error('Erro ao enviar arquivos:', error);
  });

// Faz download de um arquivo a partir de uma URL
const fileUrl = 'https://meuservidor.com/files/documento.pdf';

pbManager.downloadFile(fileUrl)
  .then((blob) => {
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'documento.pdf';
    document.body.appendChild(a);
    a.click();
    a.remove();
  })
  .catch((error) => {
    console.error('Erro ao baixar arquivo:', error);
  });

// Exclui um arquivo de um registro (campo "documento")
pbManager.deleteFile('registroId123', 'documento', 'clientes')
  .then(() => {
    console.log('Arquivo excluído do registro com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao excluir arquivo:', error);
  });

// Obtém a URL de um arquivo específico
pbManager.getFileUrl('registroId123', 'documento', 'clientes')
  .then((urlDoArquivo) => {
    console.log('URL do arquivo:', urlDoArquivo);
  })
  .catch((error) => {
    console.error('Erro ao obter URL do arquivo:', error);
  });

// Obtém as URLs de múltiplos arquivos armazenados em um array de strings
pbManager.getMultipleFileUrls('registroId789', 'documentos', 'clientes')
  .then((urlsDosArquivos) => {
    console.log('URLs dos arquivos:', urlsDosArquivos);
  })
  .catch((error) => {
    console.error('Erro ao obter múltiplas URLs de arquivos:', error);
  });

Gerenciamento de Roles

// Atribui um role a um usuário
const userId = 'usuarioId123';
const roleId = 'roleId456'; // Pode ser o ID de um registro na coleção de roles, ou um valor de string/enum

pbManager.assignRole(userId, roleId) // Por padrão, atualiza a coleção 'users'
  .then((registroAtualizado) => {
    console.log('Role atribuída:', registroAtualizado);
  })
  .catch((error) => {
    console.error('Erro ao atribuir role:', error);
  });

// Recupera todos os roles (ou usuários, dependendo da implementação) disponíveis
pbManager.getRoles() // Por padrão, lista da coleção 'users'
  .then((roles) => {
    console.log('Roles (usuários) disponíveis:', roles);
  })
  .catch((error) => {
    console.error('Erro ao obter roles:', error);
  });

Exportação e Importação de Dados

// Exporta todos os registros da coleção 'clientes' para JSON
pbManager.exportToJSON('clientes')
  .then((jsonData) => {
    console.log('Dados exportados:', jsonData);
  })
  .catch((error) => {
    console.error('Erro ao exportar dados:', error);
  });

// Importa dados a partir de uma string JSON para a coleção 'clientes'
const dadosImportados = '[{"nome":"Laura","email":"laura@exemplo.com","idade":27}]';

pbManager.importFromJSON(dadosImportados, true, 'clientes')
  .then(() => {
    console.log('Dados importados com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao importar dados:', error);
  });

// Exporta todos os registros da coleção 'clientes' para CSV
pbManager.exportToCSV('clientes')
  .then((csvData) => {
    console.log('Dados exportados para CSV:', csvData);
  })
  .catch((error) => {
    console.error('Erro ao exportar dados para CSV:', error);
  });

// Importa dados a partir de uma string CSV para a coleção 'clientes'
const dadosCSV = 'nome,email,idade\nLaura,laura@exemplo.com,27\nPedro,pedro@exemplo.com,28';

pbManager.importFromCSV(dadosCSV, true, 'clientes')
  .then(() => {
    console.log('Dados importados a partir de CSV com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao importar dados de CSV:', error);
  });

// Exporta todos os registros da coleção 'clientes' para XML
pbManager.exportToXML('clientes')
  .then((xmlData) => {
    console.log('Dados exportados para XML:', xmlData);
  })
  .catch((error) => {
    console.error('Erro ao exportar dados para XML:', error);
  });

// Importa dados a partir de uma string XML para a coleção 'clientes'
const dadosXML = '<?xml version="1.0" encoding="UTF-8"?><records><record><nome>Laura</nome><email>laura@exemplo.com</email><idade>27</idade></record></records>';

pbManager.importFromXML(dadosXML, true, 'clientes')
  .then(() => {
    console.log('Dados importados a partir de XML com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao importar dados de XML:', error);
  });

Além de exportar os dados para variáveis, você também pode fazer o download imediato dos arquivos gerados pelos métodos de exportação. Veja abaixo exemplos para JSON, CSV e XML:

// Download do arquivo JSON exportado da coleção padrão
pbManager.downloadAsJSON('clientes_export.json')
  .then(() => {
    console.log('Download de JSON concluído!');
  })
  .catch((error) => {
    console.error('Erro ao fazer download de JSON:', error);
  });

// Download do arquivo CSV exportado da coleção 'produtos'
pbManager.downloadAsCSV('produtos_export.csv', 'produtos')
  .then(() => {
    console.log('Download de CSV concluído!');
  })
  .catch((error) => {
    console.error('Erro ao fazer download de CSV:', error);
  });

// Download do arquivo XML exportado
pbManager.downloadAsXML('dados_export.xml')
  .then(() => {
    console.log('Download de XML concluído!');
  })
  .catch((error) => {
    console.error('Erro ao fazer download de XML:', error);
  });

Incrementos e Decrementos

// Incrementa o valor de um campo numérico em um registro
pbManager.increment('registroId123', 'quantidade', 5, 'estoque')
  .then((registroAtualizado) => {
    console.log('Valor incrementado:', registroAtualizado);
  })
  .catch((error) => {
    console.error('Erro ao incrementar valor:', error);
  });

// Decrementa o valor de um campo numérico em um registro
pbManager.decrement('registroId123', 'quantidade', 2, 'estoque')
  .then((registroAtualizado) => {
    console.log('Valor decrementado:', registroAtualizado);
  })
  .catch((error) => {
    console.error('Erro ao decrementar valor:', error);
  });

Eventos Locais (EventEmitter)

// Exemplo de uso do sistema de eventos locais do PocketBaseManager

// Adiciona um listener para o evento 'create'
pbManager.on('create', (novoRegistro) => {
  console.log('Registro criado (evento local):', novoRegistro);
});

// Adiciona um listener de uso único para o evento 'update'
pbManager.once('update', (registroAtualizado) => {
  console.log('Registro atualizado (evento local - once):', registroAtualizado);
});

// Remove um listener (se necessário, passando a mesma função de callback usada em 'on' ou 'once')
// const minhaFuncaoCallback = (data) => { console.log(data); };
// pbManager.on('create', minhaFuncaoCallback);
// pbManager.removeListener('create', minhaFuncaoCallback);

// Dispara manualmente um evento local
pbManager.emit('create', { id: 'teste', data: { exemplo: true } });

Verificação de Saúde do Servidor

// Verifica se o servidor PocketBase está respondendo
pbManager.healthCheck()
  .then((healthInfo) => {
    console.log('Servidor PocketBase está saudável:', healthInfo);
    // Ex: { code: 200, message: 'API is healthy.' }
  })
  .catch((error) => {
    console.error('Falha na verificação de saúde:', error.message);
  });

Referência da API

Métodos Principais

  • constructor(options): Cria uma nova instância do PocketBaseManager.
    Parâmetros:
    - options (Object): Configurações iniciais, como baseUrl, collection, cacheEnabled, cacheExpirationMinutes, syncIntervalMinutes, persistenceEnabled, disableAutoCancellation, defaultRequestOptions, maxAuditLogs.
  • isAuthenticated(): Verifica se o usuário está autenticado.
    Retorna: true se autenticado, false caso contrário.
  • login(email, password, methodRequestOptions): Realiza o login de um usuário.
    Parâmetros:
    - email (String): Email do usuário.
    - password (String): Senha do usuário.
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com os dados de autenticação.
  • getUserId(): Retorna o ID do usuário atualmente autenticado (se houver).
    Retorna: String (ID do usuário) ou undefined se não estiver autenticado.
  • signup(email, password, data, methodRequestOptions): Registra um novo usuário.
    Parâmetros:
    - email (String): Email do usuário.
    - password (String): Senha do usuário.
    - data (Object, opcional): Dados adicionais do usuário.
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com o registro criado.
  • sendPasswordResetEmail(email, methodRequestOptions): Envia um email para redefinição de senha.
    Parâmetros:
    - email (String): Email do usuário.
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve quando o email for enviado.
  • verifyEmail(token, methodRequestOptions): Verifica o email do usuário com um token.
    Parâmetros:
    - token (String): Token de verificação.
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com os dados de verificação.
  • logout(): Realiza o logout do usuário.
    Retorna: Promise que resolve quando o logout for concluído.
  • logoutAndClear(): Realiza o logout do usuário e limpa todos os dados persistidos (logs de auditoria, sessões, análises e cache).
    Retorna: Promise que resolve quando o logout e a limpeza forem concluídos.
  • create(data, collection, methodRequestOptions): Cria um novo registro em uma coleção.
    Parâmetros:
    - data (Object): Dados do registro.
    - collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão (this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com o registro criado.
  • read(id, collection, methodRequestOptions): Lê um registro pelo ID.
    Parâmetros:
    - id (String): ID do registro.
    - collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão (this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com o registro.
  • readWithAutoUpdate(id, collection, updateCallback, methodRequestOptions): Lê um registro pelo ID e atualiza automaticamente quando há novas informações (através de eventos em tempo real).
    Parâmetros:
    - id (String): ID do registro.
    - collection (String): Nome da coleção (obrigatório).
    - updateCallback (Function): Função a ser chamada com o registro atualizado.
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição inicial.
    Retorna: Promise que resolve com um objeto contendo initialData (os dados do registro inicial) e unsubscribe (uma função para cancelar a assinatura).
  • list(params, collection, methodRequestOptions): Lista registros com parâmetros de consulta.
    Parâmetros:
    - params (Object): Parâmetros de listagem, como page, perPage, filter, sort, expand.
    - collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão (this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com a lista de registros.
  • listWithAutoUpdate(params, collection, updateCallback, methodRequestOptions): Lista registros com parâmetros de consulta e atualiza automaticamente quando há novas informações (assinatura em tempo real).
    Parâmetros:
    - params (Object): Parâmetros de listagem, como page, perPage, filter.
    - collection (String): Nome da coleção (obrigatório).
    - updateCallback (Function): Função a ser chamada com a lista atualizada.
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição inicial.
    Retorna: Promise que resolve com um objeto contendo initialRecords (a lista inicial de registros) e unsubscribe (uma função para cancelar a assinatura).
  • update(id, data, collection, methodRequestOptions): Atualiza um registro existente.
    Parâmetros:
    - id (String): ID do registro.
    - data (Object): Dados a serem atualizados.
    - collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão (this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com o registro atualizado.
  • delete(id, collection, methodRequestOptions): Deleta um registro pelo ID.
    Parâmetros:
    - id (String): ID do registro.
    - collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão (this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com a resposta da deleção (geralmente true ou um objeto vazio em sucesso).
  • batchCreate(dataArray, collection, methodRequestOptions): Cria múltiplos registros em lote.
    Parâmetros:
    - dataArray (Array): Array de objetos de dados.
    - collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão (this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com os registros criados.
  • batchUpdate(idDataMap, collection, methodRequestOptions): Atualiza múltiplos registros em lote.
    Parâmetros:
    - idDataMap (Object): Mapa de IDs para dados de atualização (ex: { 'id1': { field: value }, 'id2': { field: value } }).
    - collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão (this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com os registros atualizados.
  • batchDelete(ids, collection, methodRequestOptions): Deleta múltiplos registros em lote.
    Parâmetros:
    - ids (Array): Array de IDs dos registros.
    - collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão (this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com as respostas das deleções.
  • subscribe(event, collection, callback): Assina um evento específico em uma coleção no PocketBase (tempo real).
    Parâmetros:
    - event (String): Nome do evento (ex.: 'create', 'update', 'delete', '*').
    - collection (String): Nome da coleção (obrigatório).
    - callback (Function): Função a ser chamada quando o evento ocorrer, recebendo o objeto do evento do PocketBase.
    Retorna: Promise que resolve com a função de desinscrição.
  • unsubscribe(unsubscribeFn): Desinscreve de um evento de tempo real.
    Parâmetros:
    - unsubscribeFn (Function): Função de desinscrição retornada pelo método subscribe ou um objeto com um método unsubscribe.
    Retorna: Promise que resolve quando a desinscrição for concluída.
  • uploadFile(file, collection, recordId, field, methodRequestOptions): Faz upload de um arquivo para uma coleção ou registro específico.
    Parâmetros:
    - file (File): Arquivo a ser enviado.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - recordId (String, opcional): ID do registro para associar o arquivo (cria um novo registro se não fornecido). Padrão: null.
    - field (String, opcional): Nome do campo onde o arquivo será armazenado. Padrão: 'file'.
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com um objeto contendo o registro atualizado (record) e a URL do arquivo (fileUrl).
  • uploadMultipleFiles(files, collection, recordId, field, methodRequestOptions): Faz upload de múltiplos arquivos para uma coleção ou registro específico.
    Parâmetros:
    - files (FileList ou Array): Arquivos a serem enviados.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - recordId (String, opcional): ID do registro para associar os arquivos (cria novos registros se não fornecido). Padrão: null.
    - field (String, opcional): Nome do campo onde os arquivos serão armazenados. Padrão: 'file'.
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com um array de resultados, cada um contendo { record, fileUrl } ou { error, file }.
  • downloadFile(fileUrl): Faz download de um arquivo a partir de uma URL (fetch + blob).
    Parâmetros:
    - fileUrl (String): URL do arquivo.
    Retorna: Promise que resolve com o Blob do arquivo.
  • deleteFile(recordId, fieldName, collection, methodRequestOptions): Remove um arquivo específico de um registro, definindo o campo para null.
    Parâmetros:
    - recordId (String): ID do registro.
    - fieldName (String): Nome do campo que armazena o arquivo.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve quando o arquivo for removido do registro.
  • getFileUrl(recordId, fieldName, collection, methodRequestOptions): Retorna a URL de um arquivo específico armazenado em um registro.
    Parâmetros:
    - recordId (String): ID do registro.
    - fieldName (String): Nome do campo que armazena o arquivo.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com a URL do arquivo.
  • getMultipleFileUrls(recordId, fieldName, collection, methodRequestOptions): Retorna um array de URLs para arquivos armazenados em um campo do tipo array.
    Parâmetros:
    - recordId (String): ID do registro.
    - fieldName (String): Nome do campo que armazena um array de nomes de arquivos.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com um array de URLs.
  • assignRole(userId, roleId, collection, methodRequestOptions): Atribui um role a um usuário (geralmente atualizando um campo 'role' no registro do usuário).
    Parâmetros:
    - userId (String): ID do usuário.
    - roleId (String): ID ou identificador do role.
    - collection (String, opcional): Nome da coleção de usuários (padrão: 'users').
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com o registro atualizado.
  • getRoles(collection, methodRequestOptions): Recupera todos os roles (ou registros de usuários) de uma coleção.
    Parâmetros:
    - collection (String, opcional): Nome da coleção (padrão: 'users').
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com a lista de roles (ou registros).
  • exportToJSON(collection, methodRequestOptions): Exporta todos os registros de uma coleção para uma string JSON.
    Parâmetros:
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com a string JSON.
  • importFromJSON(jsonData, overwrite, collection, methodRequestOptions): Importa registros a partir de uma string JSON.
    Parâmetros:
    - jsonData (String): String JSON contendo os dados a serem importados.
    - overwrite (Boolean, opcional): Se true, sobrescreve registros existentes com o mesmo ID. Padrão: false.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com os registros importados/atualizados.
  • downloadAsJSON(filename, collection, methodRequestOptions): Exporta todos os registros da coleção especificada (ou padrão) e inicia o download do arquivo JSON resultante.
    Parâmetros:
    - filename (String, opcional): Nome do arquivo a ser baixado (padrão: export_TIMESTAMP.json).
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição de exportação.
    Retorna: Promise que se resolve quando o download é acionado.
  • exportToCSV(collection, methodRequestOptions): Exporta todos os registros de uma coleção para uma string CSV.
    Parâmetros:
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com a string CSV.
  • importFromCSV(csvData, overwrite, collection, methodRequestOptions): Importa registros a partir de uma string CSV.
    Parâmetros:
    - csvData (String): String CSV contendo os dados a serem importados.
    - overwrite (Boolean, opcional): Se true, sobrescreve registros existentes com o mesmo ID. Padrão: false.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com os registros importados/atualizados.
  • downloadAsCSV(filename, collection, methodRequestOptions): Exporta todos os registros da coleção especificada (ou padrão) para CSV e inicia o download do arquivo.
    Parâmetros:
    - filename (String, opcional): Nome do arquivo a ser baixado (padrão: export_TIMESTAMP.csv).
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição de exportação.
    Retorna: Promise que se resolve quando o download é acionado.
  • exportToXML(collection, methodRequestOptions): Exporta todos os registros de uma coleção para uma string XML.
    Parâmetros:
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com a string XML.
  • importFromXML(xmlData, overwrite, collection, methodRequestOptions): Importa registros a partir de uma string XML.
    Parâmetros:
    - xmlData (String): String XML contendo os dados a serem importados.
    - overwrite (Boolean, opcional): Se true, sobrescreve registros existentes com o mesmo ID. Padrão: false.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com os registros importados/atualizados.
  • downloadAsXML(filename, collection, methodRequestOptions): Exporta todos os registros da coleção especificada (ou padrão) para XML e inicia o download do arquivo.
    Parâmetros:
    - filename (String, opcional): Nome do arquivo a ser baixado (padrão: export_TIMESTAMP.xml).
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição de exportação.
    Retorna: Promise que se resolve quando o download é acionado.
  • cloneRecord(id, collection, methodRequestOptions): Clona um registro existente.
    Parâmetros:
    - id (String): ID do registro a ser clonado.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com o novo registro clonado.
  • countRecords(filter, collection, methodRequestOptions): Conta o número de registros que correspondem a um filtro específico.
    Parâmetros:
    - filter (String, opcional): Filtro para contagem. Padrão: "" (sem filtro).
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com o total de registros que correspondem ao filtro.
  • searchRecords(filter, collection, perPage, methodRequestOptions): Busca registros que correspondem a um filtro específico, retornando todos os resultados (paginando internamente).
    Parâmetros:
    - filter (String, opcional): Filtro para busca. Padrão: "" (sem filtro).
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - perPage (Number, opcional): Número de registros por página para a busca interna. Padrão: 200.
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com um array dos registros encontrados.
  • sync(otherPocketBaseManagerInstance): Sincroniza dados com outra instância do PocketBaseManager (importa dados da outra instância para a atual).
    Parâmetros:
    - otherPocketBaseManagerInstance (PocketBaseManager): Outra instância do PocketBaseManager para sincronizar.
    Retorna: Promise que resolve quando a sincronização (importação) for concluída.
  • clearCache(): Limpa todo o cache de dados da coleção atual.
    Retorna: Promise que resolve quando o cache for limpo.
  • invalidateRecord(id): Invalida um registro específico no cache da coleção atual.
    Parâmetros:
    - id (String): ID do registro a ser invalidado.
    Retorna: Promise que resolve quando o registro for invalidado.
  • increment(id, field, amount, collection, methodRequestOptions): Incrementa o valor numérico de um campo em um registro.
    Parâmetros:
    - id (String): ID do registro.
    - field (String): Nome do campo a ser incrementado.
    - amount (Number, opcional): Valor a ser adicionado. Padrão: 1.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com o registro atualizado.
  • decrement(id, field, amount, collection, methodRequestOptions): Decrementa o valor numérico de um campo em um registro.
    Parâmetros:
    - id (String): ID do registro.
    - field (String): Nome do campo a ser decrementado.
    - amount (Number, opcional): Valor a ser subtraído. Padrão: 1.
    - collection (String, opcional): Nome da coleção (padrão: this.collection).
    - methodRequestOptions (Object, opcional): Opções adicionais para a requisição.
    Retorna: Promise que resolve com o registro atualizado.
  • startSync(): Inicia o processo de sincronização periódica de dados do cache da coleção atual com o servidor (baseado em syncIntervalMinutes).
    Retorna: void.
  • stopSync(): Interrompe o processo de sincronização periódica de dados.
    Retorna: void.
  • getAnalytics(): Obtém os dados de análise das operações realizadas.
    Retorna: Objeto contendo contagens de operações e uso de bytes.
  • resetAnalytics(): Reseta os dados de análise das operações realizadas.
    Retorna: void.
  • exportAnalytics(): Exporta os dados de análise das operações para uma string JSON.
    Retorna: String JSON contendo os dados de análise.
  • setDefaultCollection(collection): Define a coleção padrão para as operações e reinicia o cache e a sincronização para essa coleção.
    Parâmetros:
    - collection (String): Nome da coleção.
    Retorna: void.
  • getAuditLogs(options): Obtém os logs de auditoria com opções de filtro, ordenação e busca.
    Parâmetros:
    - options (Object, opcional): Objeto de opções para filtrar e ordenar os logs.
    - filter (String, opcional): Filtra logs pela operation. Padrão: null.
    - sortBy (String, opcional): Campo pelo qual ordenar os logs (ex: 'timestamp', 'operation'). Padrão: null.
    - searchTerm (String, opcional): Termo para buscar nos detalhes ou operação do log. Padrão: null.
    - sortOrder (String, opcional): Ordem da ordenação ('asc' ou 'desc'). Padrão: 'asc'.
    Retorna: Array de logs de auditoria.
  • deleteAuditLog(index): Deleta um log de auditoria específico pelo índice.
    Parâmetros:
    - index (Number): Índice do log a ser deletado.
    Retorna: void.
  • clearAuditLogs(): Limpa todos os logs de auditoria.
    Retorna: void.
  • exportAuditLogs(): Exporta todos os logs de auditoria para uma string JSON.
    Retorna: String JSON contendo os logs de auditoria.
  • getSessions(): Obtém todas as sessões atuais.
    Retorna: Array de sessões.
  • endSession(sessionId): Encerra uma sessão específica.
    Parâmetros:
    - sessionId (String): ID da sessão a ser encerrada.
    Retorna: void.
  • updateSessionActivity(sessionId, activity): Atualiza a atividade de uma sessão específica.
    Parâmetros:
    - sessionId (String): ID da sessão.
    - activity (String): Descrição da atividade.
    Retorna: void.
  • deleteSession(sessionId): Deleta uma sessão específica (sem disparar log de auditoria de encerramento, mas loga a deleção).
    Parâmetros:
    - sessionId (String): ID da sessão a ser deletada.
    Retorna: void.
  • clearSessions(): Limpa todas as sessões.
    Retorna: void.
  • exportSessions(): Exporta todas as sessões para uma string JSON.
    Retorna: String JSON contendo as sessões.
  • healthCheck(): Verifica a saúde do servidor PocketBase.
    Retorna: Promise que resolve com o objeto de status de saúde do servidor (ex: { code: 200, message: "API is healthy." }) ou rejeita com um erro se a verificação falhar.
  • on(event, callback): Adiciona um listener para um evento local específico (emitido internamente pelo gerenciador).
    Parâmetros:
    - event (String): Nome do evento.
    - callback (Function): Função a ser executada quando o evento ocorrer.
  • once(event, callback): Adiciona um listener para um evento local que dispara apenas uma vez.
    Parâmetros:
    - event (String): Nome do evento.
    - callback (Function): Função a ser executada quando o evento ocorrer pela primeira vez.
  • removeListener(event, callback): Remove um listener previamente adicionado para um evento local.
    Parâmetros:
    - event (String): Nome do evento.
    - callback (Function): A mesma função que foi usada em on ou once.
  • emit(event, ...args): Emite manualmente um evento local, disparando todos os callbacks registrados para ele.
    Parâmetros:
    - event (String): Nome do evento.
    - ...args (qualquer): Argumentos adicionais passados aos callbacks.

Eventos Disponíveis

  • auth: Disparado quando o status de autenticação muda (seja por 'login()', 'logout()', ou restauração via cookie).
  • signup: Disparado quando um novo usuário se registra.
  • passwordResetRequested: Disparado quando um pedido de redefinição de senha é feito.
  • emailVerified: Disparado quando o email de um usuário é verificado.
  • create: Disparado quando um novo registro é criado.
  • read: Disparado quando um registro é lido.
  • update: Disparado quando um registro é atualizado.
  • delete: Disparado quando um registro é deletado.
  • list: Disparado quando uma lista de registros é recuperada.
  • batchCreate: Disparado quando múltiplos registros são criados em lote.
  • batchUpdate: Disparado quando múltiplos registros são atualizados em lote.
  • batchDelete: Disparado quando múltiplos registros são deletados em lote.
  • fileUploaded: Disparado quando um arquivo é enviado com sucesso.
  • fileDeleted: Disparado quando um arquivo é removido de um registro.
  • getFileUrl: Disparado quando a URL de um arquivo é obtida.
  • getMultipleFileUrls: Disparado quando múltiplas URLs de arquivos são obtidas.
  • increment: Disparado quando um valor numérico de um registro é incrementado.
  • decrement: Disparado quando um valor numérico de um registro é decrementado.
  • roleAssigned: Disparado quando um role é atribuído a um usuário.
  • rolesFetched: Disparado quando os roles são recuperados.
  • import: Disparado quando dados são importados via JSON, CSV ou XML.
  • syncCompleted: Disparado quando a sincronização periódica de dados do cache com o servidor é concluída.

Configurações de Inicialização

  • baseUrl (String): URL base do servidor PocketBase. Padrão: 'http://127.0.0.1:8090'.
  • collection (String): Nome da coleção padrão a ser utilizada nas operações CRUD. Padrão: null.
  • cacheEnabled (Boolean): Habilita ou desabilita o cache de dados utilizando IndexedDB. Padrão: true.
  • cacheExpirationMinutes (Number): Define o tempo de expiração do cache em minutos. Padrão: 60.
  • syncIntervalMinutes (Number): Define o intervalo de sincronização de dados em minutos. Padrão: 10.
  • persistenceEnabled (Boolean): Habilita ou desabilita a persistência de dados (logs de auditoria, sessões e análises) utilizando IndexedDB. Padrão: true.
  • disableAutoCancellation (Boolean): Se true, desabilita o cancelamento automático de requisições do PocketBase. Padrão: false.
  • defaultRequestOptions (Object): Opções padrão a serem passadas para todas as requisições ao PocketBase SDK. Padrão: {}.
  • maxAuditLogs (Number): Número máximo de logs de auditoria a serem mantidos. Padrão: 1000.

Resolução de Problemas

Enfrentando problemas com o Easy PocketBase Manager? Aqui estão algumas soluções para problemas comuns:

  • PocketBaseManager Não Inicializa: Verifique se o script do PocketBase está sendo carregado corretamente antes do script do PocketBase Manager. Verifique o console do navegador por erros.
  • Erro de Conexão com o PocketBase: Assegure-se de que a baseUrl está correta e que o servidor PocketBase está em execução e acessível. Utilize o método healthCheck() para diagnosticar.
  • Falha na Autenticação: Verifique se as credenciais fornecidas estão corretas e se o usuário existe na coleção de usuários (padrão: 'users').
  • Operações CRUD Não Funcionam: Certifique-se de que a coleção especificada existe no PocketBase e que o usuário possui as permissões necessárias para realizar as operações. Verifique se this.collection está definido ou se você está passando o nome da coleção para o método.
  • Operações em Lote Não Funcionam: Verifique se os dados fornecidos estão no formato correto (array para batchCreate, objeto para batchUpdate, array de IDs para batchDelete).
  • Falha na Manipulação de Arquivos: Verifique se o campo especificado para o upload de arquivo existe na coleção e se o arquivo está no formato correto. Certifique-se de que o recordId é válido se estiver atualizando um registro existente.
  • Eventos Não São Disparados: Assegure-se de que os listeners de eventos estão corretamente configurados utilizando os métodos on, once e que os eventos estão sendo emitidos conforme esperado. Lembre-se que eventos de tempo real do PocketBase (via subscribe) são diferentes dos eventos locais emitidos pelo manager.
  • Falha na Importação/Exportação de Dados: Confirme se o formato do JSON, CSV ou XML está correto e se os dados correspondem à estrutura esperada pela coleção.
  • Sincronização de Dados Não Funciona: Para sync(), verifique se ambas as instâncias do PocketBaseManager estão configuradas corretamente. Para sincronização periódica (startSync()), verifique se cacheEnabled é true e se this.collection está definido.
  • Problemas de Permissões: Assegure-se de que as permissões das coleções no PocketBase estão configuradas para permitir as operações desejadas para o usuário autenticado (ou acesso público, se aplicável).
  • Erro ao Atribuir Roles: Verifique se os IDs de usuário e role fornecidos estão corretos e se a coleção de usuários (padrão 'users') possui um campo para armazenar roles (ex: 'role').
  • Problemas com o Cache: Utilize os métodos clearCache, invalidateRecord para gerenciar e resolver problemas relacionados ao cache. Lembre-se que o cache é por coleção.
  • Falha na Leitura com Atualização Automática: Verifique se os callbacks estão corretamente implementados e se a coleção especificada é válida. A função unsubscribe retornada deve ser chamada para parar de ouvir as atualizações.
  • Falha ao Gerenciar Sessões/Logs de Auditoria: Certifique-se de que persistenceEnabled está true (padrão). Verifique o console por erros relacionados ao IndexedDB.
  • Opções de Requisição (methodRequestOptions, defaultRequestOptions): Se estiver usando essas opções, certifique-se de que são válidas para o PocketBase SDK. Por exemplo, $autoCancel: false para desabilitar o cancelamento automático.

Exemplos de Código

Abaixo, alguns exemplos de como integrar e utilizar o Easy PocketBase Manager:

Exemplo Básico de Integração

<!-- Inclusão do Script do PocketBase -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/pocketbase/0.25.0/pocketbase.umd.js"></script>

<!-- Inclusão do Script do PocketBase Manager -->
<script src="https://cdn.alphasystem.dev/plugins/easy-pocketbase-manager/latest/script-min.js"></script>

<!-- Script de Configuração e Inicialização -->
<script>
  const pbManager = new PocketBaseManager({
    baseUrl: 'https://meuservidor.com', // Substitua pela URL do seu PocketBase
    collection: 'clientes', // Coleção padrão opcional
    cacheEnabled: true,
    cacheExpirationMinutes: 120,
    syncIntervalMinutes: 15,
    persistenceEnabled: true
  });

  // Exemplo de uso após inicialização
  pbManager.initPromise.then(() => {
    console.log('PocketBaseManager inicializado e pronto para uso.');
    if (pbManager.isAuthenticated()) {
      console.log('Usuário já está autenticado:', pbManager.getUserId());
    }
  }).catch(error => {
    console.error('Falha na inicialização do PocketBaseManager:', error);
  });
</script>

Autenticação de Usuário

// Realiza signup de um novo usuário
pbManager.signup('novo@usuario.com', 'senha_segura', { nome: 'Ana', idade: 28 })
  .then((registro) => {
    console.log('Usuário registrado:', registro);
  })
  .catch((error) => {
    console.error('Erro ao registrar usuário:', error);
  });

// Realiza login de um usuário existente
pbManager.login('usuario@exemplo.com', 'senha_segura')
  .then((authData) => {
    console.log('Usuário autenticado:', authData);
    // authData.record contém os dados do usuário
    // authData.token contém o token JWT
  })
  .catch((error) => {
    console.error('Erro ao autenticar usuário:', error);
  });

Gerenciamento de Registros

// Define a coleção padrão se não foi definida no construtor
// pbManager.setDefaultCollection('produtos');

// Cria um novo registro na coleção 'clientes' (ou na padrão)
pbManager.create({ nome: 'Carlos', email: 'carlos@exemplo.com', idade: 35 }, 'clientes')
  .then((registro) => {
    console.log('Registro criado:', registro);
  })
  .catch((error) => {
    console.error('Erro ao criar registro:', error);
  });

// Lê um registro pelo ID da coleção 'clientes'
pbManager.read('registroId123', 'clientes')
  .then((registro) => {
    console.log('Registro encontrado:', registro);
  })
  .catch((error) => {
    console.error('Erro ao ler registro:', error);
  });

// Atualiza um registro existente na coleção 'clientes'
pbManager.update('registroId123', { idade: 36 }, 'clientes')
  .then((registroAtualizado) => {
    console.log('Registro atualizado:', registroAtualizado);
  })
  .catch((error) => {
    console.error('Erro ao atualizar registro:', error);
  });

// Deleta um registro pelo ID da coleção 'clientes'
pbManager.delete('registroId123', 'clientes')
  .then((response) => {
    console.log('Registro deletado:', response); // true em sucesso
  })
  .catch((error) => {
    console.error('Erro ao deletar registro:', error);
  });

Operações em Lote

// Cria múltiplos registros em lote na coleção 'pedidos'
const novosRegistros = [
  { produto: 'Produto A', quantidade: 2 },
  { produto: 'Produto B', quantidade: 5 }
];

pbManager.batchCreate(novosRegistros, 'pedidos')
  .then((registrosCriados) => {
    console.log('Registros criados em lote:', registrosCriados);
  })
  .catch((error) => {
    console.error('Erro ao criar registros em lote:', error);
  });

// Atualiza múltiplos registros em lote na coleção 'pedidos'
const atualizacoes = {
  'registroId1': { quantidade: 3 },
  'registroId2': { status: 'enviado' }
};

pbManager.batchUpdate(atualizacoes, 'pedidos')
  .then((registrosAtualizados) => {
    console.log('Registros atualizados em lote:', registrosAtualizados);
  })
  .catch((error) => {
    console.error('Erro ao atualizar registros em lote:', error);
  });

// Deleta múltiplos registros em lote da coleção 'pedidos'
const idsParaDeletar = ['registroId1', 'registroId2'];

pbManager.batchDelete(idsParaDeletar, 'pedidos')
  .then((respostas) => {
    console.log('Registros deletados em lote:', respostas);
  })
  .catch((error) => {
    console.error('Erro ao deletar registros em lote:', error);
  });

Manipulação de Arquivos

// Supondo que você tenha um input de arquivo: <input type="file" id="inputArquivo">
const arquivoInput = document.querySelector('#inputArquivo');

if (arquivoInput) {
  arquivoInput.onchange = (event) => {
    const arquivo = event.target.files[0];
    if (arquivo) {
      const recordId = 'ID_DO_REGISTRO_CLIENTE'; // ID do registro ao qual o arquivo será associado
      const campoArquivo = 'avatar'; // Nome do campo de arquivo na coleção 'clientes'

      pbManager.uploadFile(arquivo, 'clientes', recordId, campoArquivo)
        .then(({ record, fileUrl }) => {
          console.log('Arquivo enviado com sucesso! Registro atualizado:', record);
          console.log('URL do arquivo:', fileUrl);
        })
        .catch((error) => {
          console.error('Erro ao enviar arquivo:', error);
        });
    }
  };
}

// Supondo input para múltiplos arquivos: <input type="file" id="inputArquivos" multiple>
const arquivosInput = document.querySelector('#inputArquivos');
if (arquivosInput) {
    arquivosInput.onchange = (event) => {
        const arquivos = event.target.files;
        if (arquivos.length > 0) {
            const recordIdMulti = 'ID_DO_REGISTRO_PROJETO';
            const campoArquivoMulti = 'anexos'; // Campo que aceita múltiplos arquivos

            pbManager.uploadMultipleFiles(arquivos, 'projetos', recordIdMulti, campoArquivoMulti)
              .then((resultados) => {
                console.log('Arquivos enviados (resultados):', resultados);
                resultados.forEach(res => {
                  if (res.error) console.error('Erro ao enviar:', res.file.name, res.error);
                  else console.log('Enviado:', res.record, res.fileUrl);
                });
              })
              .catch((error) => {
                console.error('Erro geral ao enviar múltiplos arquivos:', error);
              });
        }
    };
}


// Faz download de um arquivo a partir de uma URL (gerada pelo PocketBase ou getFileUrl)
const urlDoArquivoParaBaixar = 'URL_COMPLETA_DO_ARQUIVO_NO_POCKETBASE';
pbManager.downloadFile(urlDoArquivoParaBaixar)
  .then((blob) => {
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'nome_do_arquivo.extensao'; // Defina o nome do arquivo para download
    document.body.appendChild(a);
    a.click();
    a.remove();
    URL.revokeObjectURL(url);
    console.log('Download iniciado.');
  })
  .catch((error) => {
    console.error('Erro ao baixar arquivo:', error);
  });

// Exclui um arquivo de um registro (define o campo como null)
const recordIdComArquivo = 'ID_DO_REGISTRO_CLIENTE';
const campoDoArquivo = 'avatar';
pbManager.deleteFile(recordIdComArquivo, campoDoArquivo, 'clientes')
  .then(() => {
    console.log('Arquivo excluído do registro com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao excluir arquivo do registro:', error);
  });

// Obtém a URL de um arquivo específico
pbManager.getFileUrl(recordIdComArquivo, campoDoArquivo, 'clientes')
  .then((urlDoArquivo) => {
    console.log('URL do arquivo:', urlDoArquivo);
    // Ex: https://meuservidor.com/api/files/COLECAO_ID/REGISTRO_ID/NOME_ARQUIVO.jpg
  })
  .catch((error) => {
    console.error('Erro ao obter URL do arquivo:', error);
  });

// Obtém as URLs de vários arquivos (se o campo 'documentos' for um array de nomes de arquivos)
const recordIdComMultiplosArquivos = 'ID_DO_REGISTRO_PROJETO';
const campoComMultiplosArquivos = 'anexos';
pbManager.getMultipleFileUrls(recordIdComMultiplosArquivos, campoComMultiplosArquivos, 'projetos')
  .then((urlsDosArquivos) => {
    console.log('URLs dos arquivos:', urlsDosArquivos); // Array de URLs
  })
  .catch((error) => {
    console.error('Erro ao obter URLs dos arquivos:', error);
  });

Gerenciamento de Roles

// Atribui um role (valor no campo 'role') a um usuário na coleção 'users'
const userId = 'ID_DO_USUARIO';
const novoRole = 'admin'; // Ou pode ser um ID de outra coleção, dependendo da sua lógica

pbManager.assignRole(userId, novoRole) // Por padrão, atualiza o campo 'role' na coleção 'users'
  .then((registroAtualizado) => {
    console.log('Role atribuída ao usuário:', registroAtualizado);
  })
  .catch((error) => {
    console.error('Erro ao atribuir role:', error);
  });

// Recupera todos os usuários (que podem ter roles) da coleção 'users'
pbManager.getRoles() // Por padrão, lista da coleção 'users'
  .then((usuarios) => {
    console.log('Usuários (com seus roles):', usuarios.items);
  })
  .catch((error) => {
    console.error('Erro ao obter usuários/roles:', error);
  });

Exportação e Importação de Dados

// Exporta todos os registros da coleção 'clientes' para JSON
pbManager.exportToJSON('clientes')
  .then((jsonData) => {
    // console.log('Dados JSON exportados:', jsonData);
    // Para download direto:
    pbManager.downloadAsJSON('clientes_export.json', 'clientes');
  })
  .catch((error) => {
    console.error('Erro ao exportar dados para JSON:', error);
  });

// Importa dados a partir de uma string JSON para a coleção 'clientes', sobrescrevendo existentes
const dadosJsonParaImportar = '[{"id":"id_existente","nome":"Laura Atualizada","idade":28},{"nome":"Novo Usuário","idade":30}]';
pbManager.importFromJSON(dadosJsonParaImportar, true, 'clientes')
  .then((registrosImportados) => {
    console.log('Dados JSON importados com sucesso!', registrosImportados);
  })
  .catch((error) => {
    console.error('Erro ao importar dados JSON:', error);
  });

// Exporta para CSV e faz download
pbManager.exportToCSV('produtos')
  .then((csvData) => {
    // console.log('Dados CSV exportados:', csvData);
    pbManager.downloadAsCSV('produtos_export.csv', 'produtos');
  })
  .catch((error) => {
    console.error('Erro ao exportar dados para CSV:', error);
  });

// Importa de CSV
const dadosCSVParaImportar = 'id,nome,preco\nprod001,Produto Alfa,19.99\n,Produto Beta,29.50';
pbManager.importFromCSV(dadosCSVParaImportar, false, 'produtos') // false = não sobrescrever
  .then((registrosImportados) => {
    console.log('Dados CSV importados com sucesso!', registrosImportados);
  })
  .catch((error) => {
    console.error('Erro ao importar dados CSV:', error);
  });

Incrementos e Decrementos

// Incrementa o campo 'estoque' do registro 'produtoId123' na coleção 'produtos' em 5 unidades
pbManager.increment('produtoId123', 'estoque', 5, 'produtos')
  .then((registroAtualizado) => {
    console.log('Estoque incrementado:', registroAtualizado.estoque);
  })
  .catch((error) => {
    console.error('Erro ao incrementar estoque:', error);
  });

// Decrementa o campo 'pontos' do registro 'usuarioXyz' na coleção 'users' em 10 unidades
pbManager.decrement('usuarioXyz', 'pontos', 10, 'users')
  .then((registroAtualizado) => {
    console.log('Pontos decrementados:', registroAtualizado.pontos);
  })
  .catch((error) => {
    console.error('Erro ao decrementar pontos:', error);
  });

Eventos Locais

// Exemplo de uso dos eventos locais do PocketBaseManager

// Evento disparado após um login bem-sucedido
pbManager.on('auth', (isAuthenticated) => {
  if (isAuthenticated) {
    console.log('Evento local "auth": Usuário autenticado!', pbManager.getUserId());
  } else {
    console.log('Evento local "auth": Usuário desautenticado.');
  }
});

// Evento disparado após a criação de um registro
pbManager.on('create', (novoRegistro) => {
  console.log('Evento local "create": Novo registro criado:', novoRegistro);
  // Ex: atualizar UI com o novo registro
});

// Evento disparado uma única vez após a primeira atualização de um registro
pbManager.once('update', (registroAtualizado) => {
  console.log('Evento local "update" (disparado uma vez): Registro atualizado:', registroAtualizado);
});

// Para remover um listener específico:
// const meuListenerCreate = (data) => { console.log('Meu listener:', data); };
// pbManager.on('create', meuListenerCreate);
// pbManager.removeListener('create', meuListenerCreate); // Remove o listener específico

// Disparar um evento personalizado (se você estender a classe ou para testes)
// pbManager.emit('eventoCustomizado', { info: 'dados do evento' });