Actions

Use actions/ when your addon should extend the scripting engine itself.

What it is

An action is something a YAML script can run by id.

Use this folder when addon users should be able to write:

actions:
  - id: myAction

Where to create it

Create one file per action.

What it adds

This folder adds a new reusable YAML action to the bot.

After registration, addon users can call your action from scripts by its id.

How to create it

Rules:

• each file should export one default class
• that class must extend Action<TAddon>
• id must be unique
• onTrigger() is required
• argumentsValidator is optional, but recommended when the action accepts args

Base action API

Example from the repo

The Presets addon exposes a custom action called sendPreset.

Its pattern is the right mental model:

1. define an action-specific validator
2. resolve data from script.args
3. use the current context
4. send or edit Discord state
5. optionally call triggerFollowUpActions()

Minimal action example

import { Action, ActionArgumentsValidator, ActionData, Context, Variable } from '@itsmybot';
import { IsDefined, IsString } from 'class-validator';
import MyAddon from '..';

class ArgumentsValidator extends ActionArgumentsValidator {
  @IsDefined()
  @IsString()
  message: string;
}

export default class ExampleAction extends Action<MyAddon> {
  id = 'exampleAction';
  argumentsValidator = ArgumentsValidator;

  async onTrigger(script: ActionData, context: Context, variables: Variable[]) {
    const message = script.args.getString('message');
    this.logger.info(`Running example action with: ${message}`);
  }
}

Accessing arguments

script.args is a config-like object, so you can use getters such as:

• getString()
• getBool()
• getNumber()
• getSubsection()
• getSubsections()

If your action accepts dynamic values, combine those with Important Utils:

• Utils.applyVariables()
• Utils.evaluateNumber()
• Utils.findChannel()
• Utils.findRole()

Validating action args

Action args use validator classes the same way addon config does.

The framework already contains custom validation wiring for action argument schemas, so once your argumentsValidator is attached, YAML action configs are checked automatically.

Use Add Configuration if you want the same validation style inside your addon config files.