TaruBot

Discord bot for managing FFXIV Free Company membership in a guild: character claims/assignments, role sync, guest applications, and FC ledger entries, backed by PostgreSQL and Lodestone lookups (via Nodestone).

Setup

0. Set up Nodestone!

1. Install deps:

bun install

2. Create .env (see .env.example):

BOT_TOKEN=... (Discord bot token)
CLIENT_ID=... (Discord application/client id)
DATABASE_URL=postgres://user:password@localhost:5432/dbname
NODESTONE_BASE_URL=http://nodestone:8080
NODESTONE_CACHE_TTL_SECONDS=300
NODESTONE_MEMBERS_CACHE_TTL_SECONDS=1800
GUILD_ID=... (optional for dev guild registration)
LOG_LEVEL=info
LOG_PRETTY=true

Configuration Reference

• BOT_TOKEN (required): Discord bot token from the Developer Portal.
• CLIENT_ID (required): Discord application/client ID.
• DATABASE_URL (required): PostgreSQL connection string.
• NODESTONE_BASE_URL (required): Base URL for the Nodestone service (e.g. http://nodestone:8080).
• NODESTONE_CACHE_TTL_SECONDS (optional): Cache TTL (seconds) for Nodestone lookups. Defaults to 300.
• NODESTONE_MEMBERS_CACHE_TTL_SECONDS (optional): Cache TTL (seconds) for FC member lists. Defaults to 1800.
• GUILD_ID (optional): Target guild for development command registration. When set, commands register instantly to that guild.
• LOG_LEVEL (optional): Pino log level. Defaults to info.
• LOG_PRETTY (optional): Set to true for human-friendly console logs. Defaults to false.

Troubleshooting Config Errors

If config validation fails on startup, you'll see an error like:

Error: Invalid configuration: BOT_TOKEN is required; CLIENT_ID is required

Fix the missing or invalid env vars in .env and restart the bot.

Common Discord Setup Mistakes

• Missing privileged intents in the Developer Portal (Server Members/GUILD_MEMBERS).
• Invalid token pasted into BOT_TOKEN (ensure it's the bot token, not the client secret).
• Wrong CLIENT_ID (must match the application ID for your bot).

Run

bun run dev

Database

Run migrations before starting the bot:

bun run db:migrate

Notes

• If GUILD_ID is set, commands register instantly to that guild. Otherwise they register globally (can take up to an hour to propagate).
• Commands live in src/commands (one file per command) and events in src/events (one file per event).
• The bot expects a Nodestone service available at NODESTONE_BASE_URL.
• The bot uses the GuildMembers intent for role updates and nickname edits.