@enerthya-labs/status

Status embed system for the Enerthya Discord bot.

Provides constants, embed builders, formatters, validators and a dashboard-side StatusMonitor that edits the embed via Discord REST when the bot is offline.

Exports

Constants

| Name | Description | |------|-------------| | BOT_STATUS | ONLINE, OFFLINE, RESTARTING, DEGRADED | | DASHBOARD_STATUS | ONLINE, OFFLINE | | EMBED_COLORS | Hex color numbers for each status | | STATUS_EMOJI | Display emojis for each status | | DEFAULT_MONITOR_INTERVAL_MS | 30 000 — dashboard polling interval | | DEFAULT_BOT_REFRESH_INTERVAL_MS | 60 000 — bot embed refresh interval |

Embed Builders

All embeds use a 3-field-per-row layout (2 real + 1 blank spacer per row) to prevent inline stacking on Discord mobile when a thumbnail is present.

| Function | Description | |----------|-------------| | buildOnlineEmbed(data) | Green embed with ping, uptime, servers, members | | buildOfflineEmbed(opts?) | Red embed — rendered by dashboard when bot is down | | buildRestartingEmbed(opts?) | Yellow embed for planned restarts | | buildDegradedEmbed(data) | Orange embed when bot is up but degraded | | buildStatusEmbed(botStatus, data) | Auto-selects the right builder |

buildStatusComponents(opts?)

Returns the Discord ActionRow with the refresh interval button.

buildStatusComponents()
// → "Atualiza a cada 1 minuto"

buildStatusComponents({ intervalMs: 120_000 })
// → "Atualiza a cada 2 minutos"

| Option | Type | Default | Description | |--------|------|---------|-------------| | intervalMs | number | DEFAULT_BOT_REFRESH_INTERVAL_MS | Shown in the button label |

Formatters

| Function | Example | |----------|---------| | formatUptime(seconds) | "2d 4h 13m 7s" | | formatPing(ms) | "42ms ⚡" / "350ms ⚠️" | | formatCount(n) | "12.345" | | formatDate(date) | "15/01/2024, 12:00" | | discordRelativeTimestamp(date) | "<t:1705320000:R>" |

Validators

| Function | Returns | |----------|---------| | validateBotStatusData(data) | { valid, errors? } | | validateOfflineData(data) | { valid, errors? } |

StatusMonitor

Dashboard-side class. Polls /internal/status every N seconds. On bot going offline (after failureThreshold consecutive failures), edits all status embeds via Discord REST. Single-failure false positives are suppressed by the threshold.

const { StatusMonitor } = require("@enerthya-labs/status");

const monitor = new StatusMonitor({
  botInternalUrl:   process.env.BOT_URL,
  internalToken:    process.env.INTERNAL_API_TOKEN,
  discordToken:     process.env.TOKEN,
  getEmbedTargets:  async () => {
    const guilds = await Guild.find({ "status_embed.enabled": true });
    return guilds
      .map(g => ({ channelId: g.status_embed.channel_id, messageId: g.status_embed.message_id }))
      .filter(t => t.channelId && t.messageId);
  },
  intervalMs:       30_000,  // default: 30 000
  failureThreshold: 2,       // default: 2
  onStatusChange:   async (newStatus, prevStatus) => {
    console.log(`Bot: ${prevStatus} → ${newStatus}`);
  },
});

monitor.start();

// Force an immediate check
await monitor.forceCheck();

// Read diagnostics
console.log(monitor.info);
// { status, running, consecutiveFailures, failureThreshold, offlineSince, intervalMs }

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | botInternalUrl | string | required | Bot internal API URL | | internalToken | string | required | x-internal-token value | | discordToken | string | required | Discord bot token | | getEmbedTargets | Function | required | async () => [{ channelId, messageId }] | | intervalMs | number | 30_000 | Polling interval | | failureThreshold | number | 2 | Consecutive failures before marking offline | | onStatusChange | Function | — | async (newStatus, prevStatus) => void | | logger | object | console | Logger with .info() .warn() .error() |

API

| Member | Description | |--------|-------------| | start() | Start polling. Idempotent. | | stop() | Stop polling. | | forceCheck() | Immediate check, doesn't reset interval. | | currentStatus | Last known status string or null. | | info | { status, running, consecutiveFailures, failureThreshold, offlineSince, intervalMs } |