Coming from Necord

// Options are declared on a class, and read with @Options()
class GreetOptions {
  @StringOption({ name: 'name', description: 'Who to greet', required: true })
  name: string
}

@Injectable()
export class GreetCommand {
  constructor(private readonly greetings: GreetingService) {}

  @SlashCommand({ name: 'greet', description: 'Greets someone' })
  async greet(@Context() [interaction]: SlashCommandContext, @Options() { name }: GreetOptions) {
    await interaction.reply({ content: this.greetings.build(name) })
  }
}

@Injectable()
export class GreetingService {
  build(name: string): string {
    return `Hello, ${name}!`
  }
}

@CommandBuilder(CommandType.SLASH)
export class GreetingCommandBuilder {
  build(commandName: string) {
    return new SlashCommandBuilder()
      .setName(commandName)
      .setDescription('Greets someone')
      .addStringOption(option => option.setName('name').setDescription('Who to greet').setRequired(true))
  }
}

import { type ChatInputCommandInteraction } from 'discord.js'
import { respond } from 'meocord/common'
import { Command, Controller, Cooldown } from 'meocord/decorator'
import { GreetingCommandBuilder } from '@src/controllers/slash/builders/greeting.builder'
import { GreetingService } from '@src/services/greeting.service'

@Controller()
export class GreetingSlashController {
  constructor(private readonly greetingService: GreetingService) {}

  @Command('greet', GreetingCommandBuilder)
  @Cooldown({ uses: 3, seconds: 10 })
  async greet(interaction: ChatInputCommandInteraction, { name }: { name: string }) {
    await respond(interaction).send({ content: this.greetingService.buildGreeting(name) })
  }
}

@Service()
export class GreetingService {
  buildGreeting(name: string): string {
    return `Hello, ${name}!`
  }
}

// A Nest guard reads the interaction out of Nest's execution context
@Injectable()
class OwnerGuard implements CanActivate {
  async canActivate(context: ExecutionContext) {
    const [interaction] = NecordExecutionContext.create(context).getContext<[ButtonInteraction]>()
    const [, ownerId] = interaction.customId.split('/')
    if (interaction.user.id === ownerId) return true
    await interaction.reply({ content: 'Only the user who opened this can use it.', flags: MessageFlags.Ephemeral })
    return false
  }
}

@Injectable()
export class CardComponent {
  @Button('card/:ownerId/refresh')
  @UseGuards(OwnerGuard)
  async refresh(@Context() [interaction]: ButtonContext, @ComponentParam('ownerId') ownerId: string) {
    await interaction.update({ content: `Refreshed for <@${ownerId}> at ${new Date().toISOString()}` })
  }
}

@Command('card/{ownerId}/refresh', CommandType.BUTTON)
@UseGuard(OwnerGuard)
@Defer()
async refresh(interaction: ButtonInteraction) {
  const card = new EmbedBuilder().setTitle('Refreshed').setTimestamp()
  // Without `components`, the buttons come back as they were before the lock
  await respond(interaction).send({ embeds: [card] })
}

import { type ButtonInteraction } from 'discord.js'
import { GuardDeniedError } from 'meocord/common'
import { Guard } from 'meocord/decorator'
import { type GuardInterface } from 'meocord/interface'

/** Lets only the user whose id the button carries use it: `card/{ownerId}/…` */
@Guard()
export class OwnerGuard implements GuardInterface {
  canActivate(interaction: ButtonInteraction, { ownerId }: { ownerId: string }): boolean {
    // Thrown, it is answered privately; returning false would deny silently
    if (interaction.user.id !== ownerId) throw new GuardDeniedError('Only the user who opened this can use it.')
    return true
  }
}

// A text command receives its words as strings; the prefix is NecordModule's `prefix` option
@Injectable()
export class RollCommand {
  @TextCommand({ name: 'roll', description: 'Rolls a die' })
  async roll(@Context() [message]: TextCommandContext, @Arguments() words: string[]) {
    const sides = Number(words[0])
    if (!Number.isInteger(sides) || sides < 2) return message.reply('Usage: !roll <sides> [note]')
    const note = words.slice(1).join(' ')
    const result = 1 + Math.floor(Math.random() * sides)
    return message.reply(note ? `${result} (${note})` : String(result))
  }
}

// !roll 20 for initiative  gives  { sides: 20, note: 'for initiative' }
@MessageHandler('roll {sides} {note...?}')
@Validate(z.object({ sides: z.coerce.number().int().min(2).max(100), note: z.string().optional() }))
async roll(message: Message, { sides, note }: { sides: number; note?: string }) {
  const result = 1 + Math.floor(Math.random() * sides)
  await message.reply(note ? `${result} (${note})` : String(result))
}

// A Nest exception filter, applied with @UseFilters or globally, reads the interaction from Necord's host
@Catch()
export class CommandErrorFilter implements ExceptionFilter {
  async catch(error: unknown, host: ArgumentsHost) {
    const [interaction] = NecordArgumentsHost.create(host).getContext<[ChatInputCommandInteraction]>()
    console.error(error)
    if (interaction.isRepliable() && !interaction.replied) {
      await interaction.reply({ content: 'Something went wrong.', flags: MessageFlags.Ephemeral })
    }
  }
}

import { type ExecutionContext } from 'meocord/common'
import { Catch } from 'meocord/decorator'
import { type ExceptionFilter } from 'meocord/interface'

export class UnknownAccountError extends Error {}

@Catch(UnknownAccountError)
export class UnknownAccountFilter implements ExceptionFilter<UnknownAccountError> {
  async catch(error: UnknownAccountError, context: ExecutionContext) {
    // The params as they were when the error was thrown: here the pipe threw, so the uid is still the text
    const { uid } = context.getHandlerParams<{ uid: string }>() ?? {}
    await context.response?.error(error, { message: `There is no account ${uid}.`, visibility: 'private' })
  }
}

@Injectable()
export class WelcomeListener {
  @On('guildMemberAdd')
  async greet(@Context() [member]: ContextOf<'guildMemberAdd'>) {
    await member.send(`Welcome to ${member.guild.name}!`)
  }
}

// A Nest module lists every provider, handlers included; Necord finds the decorated ones among them
@Module({
  imports: [
    NecordModule.forRoot({
      token: process.env.DISCORD_TOKEN!,
      intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMembers],
    }),
  ],
  providers: [GreetingService, GreetCommand, CardComponent, WelcomeListener],
})
class AppModule {}

await NestFactory.createApplicationContext(AppModule)

import { type Client, type GuildMember } from 'discord.js'
import { Controller, On, Once } from 'meocord/decorator'

@Controller()
export class WelcomeController {
  // Every time a member joins; needs the GuildMembers intent
  @On('guildMemberAdd')
  async greet(member: GuildMember) {
    await member.send(`Welcome to ${member.guild.name}!`)
  }

  // The first time the client is ready, and never again
  @Once('clientReady')
  async warmCache(client: Client<true>) {
    await client.guilds.fetch()
  }
}

import { GatewayIntentBits, Partials } from 'discord.js'
import { MeoCord } from 'meocord/decorator'
import { WelcomeController } from '@src/controllers/event/welcome.controller'
import { DiceMessageController } from '@src/controllers/message/dice.message.controller'
import { KeywordMessageController } from '@src/controllers/message/keyword.message.controller'
import { StarReactionController } from '@src/controllers/reaction/star.reaction.controller'
import { ReminderScheduler } from '@src/services/reminder.scheduler'

@MeoCord({
  controllers: [DiceMessageController, KeywordMessageController, StarReactionController, WelcomeController],
  services: [ReminderScheduler],
  clientOptions: {
    intents: [
      GatewayIntentBits.Guilds,
      // Messages, and their content, for @MessageHandler
      GatewayIntentBits.GuildMessages,
      GatewayIntentBits.MessageContent,
      // Reactions for @ReactionHandler, with the partials for messages sent before the bot started
      GatewayIntentBits.GuildMessageReactions,
      // guildMemberAdd, for @On in WelcomeController
      GatewayIntentBits.GuildMembers,
    ],
    partials: [Partials.Message, Partials.Reaction],
  },
  // Patterned message handlers match after a !, or a mention of the bot
  messages: { prefix: '!', mention: true },
})
export default class App {}

import { ChatInputCommandInteraction } from 'discord.js'
import { createChatInputOptions, createMockInteraction, getResponse, MeoCordTestingModule } from 'meocord/testing'
import { describe, expect, it } from 'vitest'
import { GreetingSlashController } from '@src/controllers/slash/greeting.slash.controller'

describe('GreetingSlashController', () => {
  const module = MeoCordTestingModule.create({ controllers: [GreetingSlashController] }).compile()

  it('greets by name', async () => {
    const interaction = createMockInteraction(ChatInputCommandInteraction)
    interaction.options = createChatInputOptions({ name: 'Ada' })

    await module.invoke(GreetingSlashController, 'greet', interaction)

    expect(getResponse(interaction).calls).toEqual([
      { method: 'reply', payload: expect.objectContaining({ content: 'Hello, Ada!' }) },
    ])
  })
})