Expansions

Use expansions/ when your addon needs custom placeholders.

What it is

An expansion adds a placeholder namespace that can be used in text.

That produces placeholders like:

%myexpansion_value%

Where to create it

Create one file per expansion.

What it adds

This folder adds new placeholders that the bot can resolve in text and scripts.

That is useful when addon data should be reusable in many messages.

How to create it

Rules:

• each file should export one default class
• that class must extend Expansion<TAddon>
• name is the placeholder namespace
• onRequest() should return a string or undefined

Base expansion API

Example

import { Expansion, Context } from '@itsmybot';
import MyAddon from '..';

export default class ExampleExpansion extends Expansion<MyAddon> {
  name = 'example';

  async onRequest(context: Context, placeholderName: string) {
    if (placeholderName === 'status') return 'online';
    return undefined;
  }
}

This would allow:

%example_status%

Good expansion patterns

• keep the placeholder namespace short and stable
• parse the placeholder tail yourself inside onRequest()
• cache expensive remote calls when needed
• return undefined when the placeholder should not be replaced

The MCStatus addon is the best reference in the repo for a real-world expansion with caching and placeholder parsing.

Nested placeholders

The expansion service also supports nested placeholder resolution inside placeholder arguments.

That means expansion logic should assume placeholder input may already have been partially resolved before onRequest() receives it.