@luxorbots/fac-shared-db

Schemas Mongoose e helper de conexão compartilhados entre os bots do ecossistema Luxor: fac-control-bot (registro central / control-plane), fac-assist-bot e fac-helper-bot (bots por servidor/tenant, compartilhando o mesmo banco). Este pacote existe pra que o formato de uma collection genuinamente lida/escrita por mais de um desses bots seja definido em um único lugar, em vez de duplicado/hand-rolled em cada um.

Só entra aqui o que é cross. Um model usado por um único bot vive no repo desse bot, não neste pacote — isso já foi feito uma vez (ver changelog: ~19 models saíram daqui em 2026-08 porque só tinham um consumidor).

Instalação

npm install @luxorbots/fac-shared-db

Requer Node.js 22 ou superior.

Uso

import { connectDatabase, ServidorModel } from "@luxorbots/fac-shared-db";

await connectDatabase(process.env.MONGO_URI!, process.env.DB_NAME);

const servidores = await ServidorModel.find({ ativo: true });

connectDatabase(uri, dbName?) não conhece cluster, host ou appName de nenhum bot — cada bot monta sua própria connection string a partir das próprias env vars e decide como reagir a falha de conexão (retry, log, process.exit, etc). Isso mantém o pacote agnóstico em relação a qual bot o está consumindo.

modelOn(connection, name, schema) resolve um model numa connection específica (useDb), sem duplicar a definição do schema — usado pelo padrão multi-tenant (1 banco por servidor) e pelas escritas cross-db no banco mestre do fac-control-bot.

limparCollectionsOrfas(connection, nomesOrfaos) remove, no boot, collections vazias de models que o barrel export registrou na connection default mas que aquele bot específico nunca usa (ver seção abaixo sobre o efeito colateral do barrel).

Collections

| Model | Collection (Mongo) | Propósito | | --- | --- | --- | | ServidorModel | servidors | Registro central de servidores/tenants (banco do fac-control-bot) | | CidadeModel | cidades | Cidade — agrupa Servidores e Facções (banco do fac-control-bot) | | FaccaoModel | faccaos | Facção dentro de uma Cidade (banco do fac-control-bot) | | AcoesConfigModel | acoesconfigs | Calendário semanal de ações + config de webhook (banco de cada tenant) | | BaqueMarcadoModel | baquesmarcados (override explícito) | Baque marcado por uma facção contra outra, dentro da mesma cidade | | Caixa2ItemModel | caixa2itens (override explícito) | Itens do baú com limites de advertência | | LogsExporterGuildConfigModel | logsexporterguildconfigs | Config de exportação de logs por guild/evento | | MensagemRecrutamentoModel | mensagemrecrutamentos | Singleton (_id: "RECRUTAMENTO"): texto de recrutamento vigente | | BlacklistModel | blacklist (override explícito) | Banimento de jogadores, com TTL automático — escopo por Cidade, escrita também cross-db no banco mestre do fac-control-bot | | KeyValueModel | keyvalues | Storage genérico key-value |

Nomes de collection sem "override explícito" são o default do Mongoose (pluralização automática do nome do model) — não dependem de nenhuma string hardcoded neste pacote.

Quem lê/escreve o quê hoje

• fac-control-bot: dono de Servidor/Cidade/Faccao (painel admin, banco próprio). Nunca lê AcoesConfig/BaqueMarcado/Caixa2Item/LogsExporterGuildConfig/MensagemRecrutamento na própria connection default — só existem lá como efeito colateral do barrel (ver limparCollectionsOrfas no fac-control-bot).
• fac-assist-bot e fac-helper-bot: rodam por tenant, compartilhando o banco daquele servidor. AcoesConfig/BaqueMarcado/Caixa2Item/LogsExporterGuildConfig/MensagemRecrutamento são escritos por um lado e lidos pelo outro dentro do mesmo banco — é por isso que esses ficam aqui e não em um dos dois repos.
• Blacklist: fac-helper-bot lê/escreve local (por tenant) e também mantém uma cópia mestre no banco do fac-control-bot via useDb cross-db; fac-assist-bot só toca nela via reset administrativo (getContextModel, connection por guild, não a default).
• KeyValue: usado pelos 3 bots, cada um na sua própria connection.

Efeito colateral do barrel export (leia antes de adicionar um model órfão)

Importar qualquer coisa deste pacote registra todos os models do barrel na connection default de quem importou (mongoose.model(...) roda no module scope de cada arquivo). Sem autoCreate/autoIndex desligados, isso cria (vazia) a collection de todo model que o bot consumidor nunca usa — inclusive dos outros dois bots. Os 3 bots consumidores desligam autoCreate/autoIndex e usam limparCollectionsOrfas numa allowlist explícita pra limpar o que sobra. Isso é o principal motivo pra não trazer de volta um model de uso único pra cá — cada entrada aqui é uma linha a mais na allowlist de limpeza dos outros dois bots que não usam.

Ao adicionar uma collection nova usada por mais de um bot, ela nasce neste pacote — não em um dos bots individualmente. Ao perceber que uma collection daqui só tem 1 consumidor de verdade, ela deve sair daqui e virar model local do bot dono.