Shiver Framework

framework.use(async (context, next) => {
    const { interaction, message, command, client } = context;
    await next();
});

const framework = new ShiverFramework({
    commandsPath: './src/commands',
    prefix: ',',
    async getPrefix(message, fw) {
        if (!message.guildId) return ',';
        return await fw.settings.getGuildPrefix(message.guildId, null) ?? ',';
    }
});

framework.health.addRoute('GET', '/api/bot', async (req, res, url) => {
    return {
        name: 'MyBot',
        version: '1.0.0',
        commands: framework.commands.getAllSlash().length
    };
});

await framework.init(client);
const gatewayMs = framework.ping.getGatewayMs();
const restMs = await framework.ping.getRestMs();
const full = await framework.ping.getFullPing();

const result = await framework.httpPush('https://your-site.com/api/stats', {
    guilds: client.guilds.cache.size,
    commands: framework.commands.getAllSlash().length
}, { method: 'POST', timeoutMs: 5000 });

const payload = { content: 'Done.', ephemeral: true };
await framework.followUp(interaction, payload);

const { FunctionRegistry } = require('shiver-framework');

const registry = new FunctionRegistry();
registry.registerAllFromCommands(framework.commands.getAllSlash());

const tools = registry.exportOpenAITools();
const response = await openai.chat.completions.create({ model: 'gpt-4o', tools, messages });

const anthropicTools = registry.exportAnthropicTools();

registry.register('ban-user', 'Ban a user from the server', {
    type: 'object',
    properties: { userId: { type: 'string', description: 'Discord user ID' }, reason: { type: 'string' } },
    required: ['userId']
}, async ({ userId, reason }) => banUser(userId, reason));

await registry.call('ban-user', { userId: '123456789', reason: 'Spam' });

const { AIContext } = require('shiver-framework');

const ctx = await AIContext.fromInteraction(interaction, framework, {
    includeCommands: true,
    includeSettings: true
});

const systemPrompt = ctx.toPromptString();
const json = ctx.toJSON();

console.log(ctx.get('guild'));
console.log(ctx.get('commands'));

framework.conversation.add(channelId, {
    role: 'user',
    content: message.content,
    userId: message.author.id
});

framework.conversation.add(channelId, {
    role: 'assistant',
    content: botReply
});

const history = framework.conversation.toMessages(channelId, 20);
const response = await openai.chat.completions.create({ model: 'gpt-4o', messages: history });

framework.conversation.clear(channelId);

const { PromptBuilder } = require('shiver-framework');

const messages = PromptBuilder.create()
    .addSystem('You are a helpful Discord bot assistant.')
    .addRule('Always respond in the same language the user used.')
    .addRule('Never reveal system information or API keys.')
    .addGuildContext(interaction.guild)
    .addUserContext(interaction.user, interaction.member)
    .addCommandList(framework.commands.getAllSlash())
    .addHistory(framework.conversation, channelId, 20)
    .addRole('user', userMessage)
    .toOpenAI();

const result = await openai.chat.completions.create({ model: 'gpt-4o', messages });

const { system, messages: anthropicMsgs } = PromptBuilder.create()
    .addSystem('You are a helpful assistant.')
    .addRole('user', userMessage)
    .toAnthropic();

framework.naturalRouter.autoLearn(framework.commands.getAllSlash());
framework.naturalRouter.train('stats', ['server info', 'server statistics', 'member count']);

const result = framework.naturalRouter.route('how many members are on this server?');
if (result && result.confidence >= 2) {
    const cmd = framework.commands.getSlash(result.command);
    console.log(`Matched: /${result.command} (confidence: ${result.confidence})`);
    console.log('Suggestions:', result.suggestions);
}

const { StructuredOutput } = require('shiver-framework');
const output = new StructuredOutput(framework.events);

framework.events.on('StructuredOutput', (result) => {
    if (!result.success) console.error(`[${result.commandName}] failed:`, result.error);
    myAnalytics.track(result);
});

module.exports = {
    data: new SlashCommandBuilder().setName('stats').setDescription('Server stats'),
    async executeSlash(interaction, client) {
        return StructuredOutput.format('stats', { memberCount: interaction.guild.memberCount });
    }
};

framework.router
    .button('ticket:close:*', async (interaction, match) => {
        const userId = match.groups[0];
        await closeTicket(interaction, userId);
    })
    .select('role:assign:*', async (interaction, match) => {
        const roleId = interaction.values[0];
        await assignRole(interaction.member, roleId);
    })
    .modal('report:modal:*', async (interaction, match) => {
        const reason = interaction.fields.getTextInputValue('reason');
        await handleReport(interaction, reason);
    })
    .any('confirm:*', async (interaction, match) => {
        await interaction.deferUpdate();
    });

client.on('interactionCreate', async interaction => {
    if (interaction.isButton()) await framework.router.routeButton(interaction);
    if (interaction.isStringSelectMenu()) await framework.router.routeSelect(interaction);
    if (interaction.isModalSubmit()) await framework.router.routeModal(interaction);
});

const { WizardSession } = require('shiver-framework');

const wizard = new WizardSession(interaction, [
    {
        name: 'ticket-reason',
        async run(wizard, i) {
            await i.reply({ content: 'Briefly describe your issue:', ephemeral: true });
            const collected = await i.channel.awaitMessages({
                filter: m => m.author.id === i.user.id, max: 1, time: 60000
            });
            wizard.setData('reason', collected.first()?.content ?? '');
        }
    },
    {
        name: 'ticket-priority',
        async run(wizard, i) {
            wizard.setData('priority', 'normal');
        }
    }
], {
    timeoutMs: 120000,
    onTimeout: async (wiz) => { /* clean up */ },
    onCancel: async (wiz) => { /* handle cancel */ }
});

const data = await wizard.run();
console.log(data.reason, data.priority);

const { FormBuilder } = require('shiver-framework');
const { TextInputStyle } = require('discord.js');

const form = new FormBuilder('Submit Report', 'report:modal')
    .addField('title', 'Report Title', { required: true, maxLength: 100 })
    .addField('details', 'What happened?', {
        style: TextInputStyle.Paragraph,
        required: true,
        minLength: 20
    })
    .addField('link', 'Message link', {
        required: false,
        regex: /^https:\/\/discord\.com\/channels\//
    });

await interaction.showModal(form.build());

const submitted = await interaction.awaitModalSubmit({ time: 120000 });
const { values, errors, ok } = form.parse(submitted);

if (!ok) {
    return submitted.reply({ content: errors[0].message, ephemeral: true });
}
await handleReport(values.title, values.details);

const { VoteManager } = require('shiver-framework');
const votes = new VoteManager();

const pollId = votes.create(channelId, ['Yes', 'No', 'Maybe'], {
    title: 'Should we add a music bot?',
    timeoutMs: 300000,
    anonymous: true
});

votes.cast(pollId, userId, 0);
votes.retract(pollId, userId);
votes.cast(pollId, userId, 1);

const results = votes.getResults(pollId);
console.log(results.options);
console.log(`Winner: ${results.winner.label} with ${results.winner.votes} votes`);

const final = votes.end(pollId);

const { MessageCollector } = require('shiver-framework');

const { content } = await MessageCollector.prompt(
    channel, userId, 'What is your preferred username?',
    {
        timeoutMs: 30000,
        validator: (value) => value.length < 3 ? 'Username must be at least 3 characters.' : true
    }
);

const answers = await MessageCollector.sequence(channel, userId, [
    { key: 'name', question: 'What is your name?' },
    { key: 'age', question: 'How old are you?', validator: v => isNaN(v) ? 'Enter a number.' : true }
]);
console.log(answers.name, answers.age);

framework.sessions.set(userId, 'step', 'confirm', 60000);
framework.sessions.set(userId, 'pendingBanTarget', targetUserId);

const step = framework.sessions.get(userId, 'step');
const all = framework.sessions.getAll(userId);

if (framework.sessions.has(userId, 'pendingBanTarget')) {
    framework.sessions.touch(userId);
    const target = framework.sessions.get(userId, 'pendingBanTarget');
    framework.sessions.delete(userId, 'pendingBanTarget');
}

framework.scheduler.every(30000, 'heartbeat', async () => {
    console.log('[heartbeat] ping:', framework.client.ws.ping);
});

framework.scheduler.cron('0 9 * * *', 'daily-report', async () => {
    await reportChannel.send('Good morning! Daily report:');
});

framework.scheduler.once(5000, 'startup-announce', async () => {
    await announceChannel.send('Bot is online!');
});

framework.scheduler.pause('heartbeat');
framework.scheduler.resume('heartbeat');
framework.scheduler.cancel('heartbeat');

console.log(framework.scheduler.list());

const { sent, failed } = await framework.broadcast.send(
    ['channelId1', 'channelId2', 'channelId3'],
    { content: 'Maintenance in 10 minutes.' }
);
console.log(`Sent: ${sent.length}, Failed: ${failed.length}`);

await framework.broadcast.sendToGuilds(
    ['guildId1', 'guildId2'],
    async (guild) => guild.systemChannel,
    { content: 'Thanks for using our bot!' }
);

await framework.broadcast.dm(
    ['userId1', 'userId2'],
    { content: 'Your subscription has been renewed.' }
);

const { RequestDeduplicator } = require('shiver-framework');
const dedup = new RequestDeduplicator({ ttlMs: 500 });

async function getGuildSettings(guildId) {
    return dedup.run(`settings:${guildId}`, () => db.fetchSettings(guildId));
}

dedup.invalidate(`settings:${guildId}`);
dedup.clear();

const { safeRun, withRetry, withTimeout } = require('shiver-framework');

const data = await safeRun(() => fetchExternalAPI(), {
    retries: 3,
    timeoutMs: 5000,
    delayMs: 500,
    onError: (err) => console.error('[API] error:', err.message),
    fallback: null
});

const result = await withRetry(() => db.query(), 3, 300);
const val = await withTimeout(() => heavyOperation(), 10000);

framework.flags
    .define('new-leveling', { default: false, description: 'New XP algorithm rollout' })
    .define('beta-music', { default: false });

const enabled = await framework.flags.isEnabled('new-leveling', { guildId });
if (enabled) {
    await newLevelingLogic(interaction);
} else {
    await legacyLevelingLogic(interaction);
}

await framework.flags.enable('beta-music', { guildId: '123456789' });
await framework.flags.disable('beta-music', { userId: specificUserId });
const all = await framework.flags.getAll({ guildId });

const { CommandDisabledManager } = require('shiver-framework');
const cmdDisabled = new CommandDisabledManager(framework.storage);

await cmdDisabled.disable('music', guildId);
await cmdDisabled.enable('music', guildId);

const isOff = await cmdDisabled.isDisabled('music', guildId);
const list = await cmdDisabled.getDisabledCommands(guildId);

await cmdDisabled.disableAll(guildId, ['music', 'giveaway']);

const { HelpGenerator } = require('shiver-framework');

const text = HelpGenerator.generate(framework.commands.getSlash('report'));
const list = HelpGenerator.generateList(framework.commands.getAllSlash());
const modCmds = HelpGenerator.generateCategory(framework.commands.getAllSlash(), 'moderation');

const { CommandSuggester } = require('shiver-framework');
const suggester = new CommandSuggester();

const suggestions = suggester.suggest('stast', framework.commands.getAllSlash(), 3);
if (suggestions.length) {
    await message.reply(`Did you mean: ${suggestions.map(s => \`\`,\${s.command}\`\`).join(', ')}?`);
}

const { diff, formatDiff } = require('shiver-framework');

const before = { color: '#5865F2', prefix: ',', language: 'en' };
const after  = { color: '#ED4245', prefix: '!', language: 'en', theme: 'dark' };

const changes = diff(before, after);
const text = formatDiff(changes);
// ~ **color**: `#5865F2` to `#ED4245`
// ~ **prefix**: `,` to `!`
// + **theme**: `dark`

framework.alerts
    .define('high-errors', stats => stats.get('errors') ?? 0, 50, async ({ value }) => {
        await alertChannel.send(`High error rate: ${value} errors`);
    }, { cooldownMs: 300000, compare: 'gt' })
    .define('low-guilds', stats => stats.get('guilds') ?? 0, 5, async ({ value }) => {
        console.warn(`Only ${value} guilds left!`);
    }, { compare: 'lt' });

framework.alerts.startPolling(60000);
await framework.alerts.checkAll();
framework.alerts.stopPolling();

const { localizeCommand, localizeAll } = require('shiver-framework');

const locales = ['pl', 'de', 'fr'];

const localizedData = localizeCommand(command.data, framework.i18n, locales);
const allLocalized = localizeAll(framework.commands.getAllSlash(), framework.i18n, locales);

const { buildProgressBar, buildMultiBar } = require('shiver-framework');

buildProgressBar(750, 1000, { width: 20, showFraction: true });
// ███████████████░░░░░ 75% (750/1000)

buildProgressBar(30, 100, { filled: '▓', empty: '░', prefix: 'XP', showPercent: true });
// XP ▓▓▓▓▓▓░░░░░░░░░░░░░░ 30%

const multibar = buildMultiBar([
    { label: 'CPU', current: 72, total: 100 },
    { label: 'Memory', current: 4200, total: 8192 },
    { label: 'Disk', current: 250, total: 500 }
]);

const { TableBuilder } = require('shiver-framework');

const table = new TableBuilder()
    .addColumn('rank', '#', { width: 4, align: 'right' })
    .addColumn('name', 'Player', { width: 18 })
    .addColumn('score', 'Score', { width: 8, align: 'right' })
    .addRow({ rank: '1', name: 'Alice', score: '9800' })
    .addRow({ rank: '2', name: 'Bob', score: '7400' })
    .addSeparator()
    .addRow({ rank: '3', name: 'Charlie', score: '5200' });

await interaction.reply({ content: table.toCodeBlock(), flags: [] });

const { ListBuilder } = require('shiver-framework');

const text = new ListBuilder()
    .addSection('Server Info')
    .add('Name', guild.name, { bold: true })
    .add('Members', guild.memberCount)
    .addBlank()
    .addSection('Settings')
    .add('Prefix', framework.options.prefix, { code: true })
    .add('Language', 'en')
    .build();

const { TicketSystem } = require('shiver-framework');
const tickets = new TicketSystem(framework.storage, {
    supportRoles: ['supportRoleId'],
    categoryId: 'ticketCategoryId'
});

const { channel, ok } = await tickets.open(guild, userId, {
    welcome: { content: 'Support will be with you shortly.' }
});

const existingChannel = await tickets.isOpen(guildId, userId);

const { transcript } = await tickets.close(channel, { deleteChannel: true });
console.log(transcript.map(m => `[${m.author}] ${m.content}`).join('\n'));

const { GiveawaySystem } = require('shiver-framework');
const giveaways = new GiveawaySystem(framework.storage);

const { id } = await giveaways.start(channel, {
    prize: 'Discord Nitro',
    winnersCount: 2,
    durationMs: 3600000
});

await giveaways.enter(id, userId);
await giveaways.leave(id, userId);

const result = await giveaways.draw(id);
console.log(`Winners: ${result.winners.join(', ')}`);

const rerolled = await giveaways.reroll(id, 1);
console.log(`New winner: ${rerolled.winners[0]}`);

const { TagSystem } = require('shiver-framework');
const tags = new TagSystem(framework.storage);

await tags.create(guildId, 'rules', 'Welcome {user}! Please read <#channelId>.', userId);
await tags.create(guildId, 'ping', 'Pong! The bot is online.', userId);

const content = await tags.use(guildId, 'rules', { user: interaction.user.username });
await interaction.reply(content);

const allTags = await tags.list(guildId);
const results = await tags.search(guildId, 'rule');
await tags.update(guildId, 'rules', 'New rules content here.');
await tags.delete(guildId, 'rules');

const { StarboardSystem } = require('shiver-framework');
const starboard = new StarboardSystem(framework.storage, client);

await starboard.configure(guildId, starboardChannelId, 3, '⭐');

client.on('messageReactionAdd', async (reaction, user) => {
    await starboard.handleReaction(reaction, user);
});

const alreadyPosted = await starboard.isPosted(message.id);

const { OwnerGuard, GuildGuard, ChannelGuard, RoleGuard, TimeGuard, RateLimitGuard } = require('shiver-framework');

const ownerGuard = new OwnerGuard(['ownerId1', 'ownerId2']);
if (!ownerGuard.check(interaction.user.id)) {
    return interaction.reply({ content: 'Owner only.', ephemeral: true });
}

const guildGuard = new GuildGuard(['allowedGuildId']);
const channelGuard = new ChannelGuard(['allowedChannelId']);

const modRole = new RoleGuard(['modRoleId', 'adminRoleId']);
if (!modRole.check(interaction.member)) {
    return interaction.reply({ content: 'Mod only.', ephemeral: true });
}

const supportHours = new TimeGuard(9, 17, { timezone: 'Europe/Warsaw' });
if (!supportHours.check()) {
    return interaction.reply({ content: 'Support is only available 9-17 Warsaw time.', ephemeral: true });
}

const spamGuard = new RateLimitGuard(3, 10000);
if (!spamGuard.check(interaction.user.id)) {
    return interaction.reply({ content: 'Too many requests. Try again soon.', ephemeral: true });
}

{ type: ComponentType.TextDisplay, content: [
    '# Server Stats',
    '',
    '> **Members:** 1,234',
    '> **Online:** 456',
    '',
    '-# Updated <t:' + Math.floor(Date.now()/1000) + ':R>'
].join('\n') }

const status = online ? '<:online:1234567890>' : '<:offline:9876543210>';
const loading = '<a:loading:1122334455>';

await interaction.reply({
    content: `${loading} Fetching data for <@${userId}> in <#${channelId}>...`
});

const { ComponentType, MessageFlags } = require('discord.js');

const container = {
    type: ComponentType.Container,
    accentColor: 0x5865f2,
    components: [
        { type: ComponentType.TextDisplay, content: '# Hello World\n> Welcome to the server!' },
        { type: ComponentType.Separator, divider: true, spacing: 2 },
        { type: ComponentType.TextDisplay, content: 'This is the main content.' }
    ]
};

await interaction.reply({ components: [container], flags: MessageFlags.IsComponentsV2 });

{ type: ComponentType.Separator, divider: true, spacing: 2 }
// divider: true = visible line; false = spacing only
// spacing: 1 = Small, 2 = Large

{ type: ComponentType.MediaGallery, items: [
    { media: { url: 'attachment://shiver.png' }, description: 'Alt text' }
] }

await interaction.reply({
    components: [container],
    files: [new AttachmentBuilder(buffer, { name: 'shiver.png' })],
    flags: MessageFlags.IsComponentsV2
});

{ type: ComponentType.Section,
  components: [{ type: ComponentType.TextDisplay, content: '**Alice** - Level 42\n> XP: 8,400' }],
  accessory: { type: ComponentType.Thumbnail, media: { url: 'https://cdn.discordapp.com/avatars/...' } }
}

const { ButtonStyle } = require('discord.js');

{ type: ComponentType.ActionRow, components: [
    { type: ComponentType.Button, label: 'Confirm', style: ButtonStyle.Success, customId: 'confirm:yes:' + userId },
    { type: ComponentType.Button, label: 'Cancel', style: ButtonStyle.Secondary, customId: 'confirm:no:' + userId },
    { type: ComponentType.Button, label: 'GitHub', style: ButtonStyle.Link, url: 'https://github.com' }
] }

{ type: ComponentType.StringSelect,
  customId: 'settings:theme:' + userId,
  placeholder: 'Choose a theme...',
  minValues: 1, maxValues: 1,
  options: [
      { label: 'Dark', value: 'dark', description: 'Dark mode', emoji: { name: '🌙' }, default: true },
      { label: 'Light', value: 'light', description: 'Light mode', emoji: { name: '☀️' } }
  ]
}

const { EmbedBuilder } = require('discord.js');

const embed = new EmbedBuilder()
    .setTitle('Server Info')
    .setDescription('> **Members:** 1,234\n> **Online:** 456')
    .addFields(
        { name: 'Owner', value: '<@ownerId>', inline: true },
        { name: 'Created', value: '<t:1609459200:D>', inline: true }
    )
    .setColor(0x5865f2)
    .setThumbnail(guild.iconURL())
    .setImage('https://example.com/banner.png')
    .setFooter({ text: 'Shiver Framework', iconURL: client.user.displayAvatarURL() })
    .setTimestamp();

await interaction.reply({ embeds: [embed] });

# Shiver Framework - AI Rules

## Language & Communication
- Communicate with the user in the same language they use to talk to you.
- Use English for all code: variable names, function names, file names, and comments.
- If the user does not specify a language for communication, default to English.
- Questions are always welcome. Ask clarifying questions immediately when something is ambiguous.
- Be 100% aligned with the user's intent. Confirm understanding before implementing if anything is unclear.
- Never respond with acknowledgment phrases like "Great!", "Sure!", "Understood!" - go directly to work.
- Always finish the task completely without stopping to ask "should I continue?".

## Code Quality
- All functions must be async/await. Never use .then() or callbacks.
- No code comments. Write self-explanatory code through proper naming and structure.
- Write the absolute minimum code needed. No extra features, no unused variables.
- Always finish work fully. Do not stop midway or leave stubs.
- Before marking a task done, verify the project starts cleanly with no errors.

## Discord Bot Standards
- All new command output must use Components v2 (ContainerBuilder / raw API objects with ComponentType).
  Never use EmbedBuilder for primary command output in new code.
- Never show raw error messages, stack traces, or technical details to Discord users.
  Use generic user-facing messages and log technical details server-side only.
- All sensitive, private, or user-specific replies must be sent with MessageFlags.Ephemeral.
- For slash commands that do I/O or heavy computation, call deferReply at the very start
  (before any await) so Discord receives an acknowledgment within 3 seconds.
- Use a consistent customId scheme: command:action:userId (e.g. ticket:close:123456789).
- Collectors must have sensible timeout and idle durations. Always clean up in the "end" handler.
- Respect Discord limits: 25MB per file, 10 files per message, 5 buttons per ActionRow.

## Components v2 Rules
- Never mix components messages with embeds, content, stickers, or poll in the same reply.
- Always set MessageFlags.IsComponentsV2 on both deferReply AND editReply.
- The filename in AttachmentBuilder must exactly match the attachment:// reference.
- accentColor accepts a decimal integer (0x5865f2), not a hex string.
- Use Separator with divider: true for visual lines, divider: false for spacing only.

## Security
- Never expose API keys, tokens, secrets, or stack traces in user-facing messages.
- Log errors server-side (console.error) only. Redact sensitive data in all logs.
- All attachment filenames must use the format: shiver.(ext) or shiver_1.png for multiples.

## Framework First
- When shiver-framework is missing a generic capability, improve the framework first
  instead of adding a bot-specific workaround.
- Do not duplicate infrastructure in the bot if the concern belongs in the framework.
- Framework changes must remain broadly useful and reusable - no bot-specific hacks.

## Workspace Facts (customize for your project)
- Commands path: src/commands/
- Entry point: src/index.js
- Framework: shiver-framework (linked locally or installed from npm)
- Bot prefix: , (comma)
- Storage backend: json (or supabase / sqlite / mongo)