Runtime rules

Plugin runtime code does not run as a normal Node.js process. It runs in a sandboxed worker-style runtime and communicates with Discord by returning validated actions.

Sandbox model

Use SDK context APIs instead of Node built-ins.

Do not use runtime-only Node APIs in plugin code:

import fs from "node:fs";
import { spawn } from "node:child_process";

Use platform APIs exposed on context:

• ctx.reply() for slash command replies.
• ctx.sendMessage() for message writes from event contexts.
• ctx.ok([...actions], [...logs]) for explicit actions and logs.
• ctx.kv for simple key-value state.
• ctx.storage for declared collections.

Capabilities

Capabilities declare which Discord writes a plugin can perform. Publish validation and runtime validation both check them.

import { PluginCapability } from "itsmybot";

readonly capabilities = [
  PluginCapability.DiscordInteractionReply,
  PluginCapability.DiscordMessageWrite,
] as const;

Use this mapping:

If an action is returned without the matching capability, the runtime rejects the result.

KV state

Use ctx.kv for small, direct key-value state.

import type { MessageCreateContext } from "itsmybot";

async function countMentions(ctx: MessageCreateContext<Record<string, unknown>>) {
  if (!ctx.event.mentionedBot) {
    return ctx.ok();
  }

  const nextCount = ((await ctx.kv.get<number>("mentions:count")) ?? 0) + 1;
  await ctx.kv.set("mentions:count", nextCount);

  nextCount;
    
const nextCount: any
  return ctx.ok();
}

Good KV keys are namespaced:

mentions:count
mentions:last-at
users:123:last-command

Declared storage

Use storage when state needs collections, indexes, or queries.

readonly storage = {
  notes: {
    indexes: ["createdAt", "authorId"],
  },
};

Then read and write through ctx.storage:

import type { CommandContext } from "itsmybot";

async function saveNote(ctx: CommandContext<Record<string, unknown>>, body: string) {
  const id = crypto.randomUUID();

  await ctx.storage.notes.put(id, {
    authorId: ctx.event.userId,
    body,
    createdAt: new Date().toISOString(),
  });

  return ctx.reply("Saved.");
}

Keep collection records plain JSON. Do not store functions, class instances, or unserializable values.

Result shape

Handlers return a plugin invocation result. Usually, use context helpers:

return ctx.reply("Done.");

or:

return ctx.ok([], [
  ctx.info("Handled event."),
]);

Use ctx.fail(message) for expected plugin-level failures:

if (!input.trim()) {
  return ctx.fail("Input cannot be empty.");
}

Runtime checklist

Before publishing:

• every Discord write has a declared capability.
• command and event handlers return SDK helper results.
• runtime state uses ctx.kv or declared storage.
• command output is non-empty.
• plugin code avoids Node-only imports.
• config defaults are safe for first install.