@stambha/core

@stambha/core

Transport-agnostic Discord bot framework — client, command pipeline, registries, sequences, and tier split. No discord.js or Discordeno required.

Part of the @stambha monorepo · GitHub · Docs

---

Install

npm install @stambha/core
# or
pnpm add @stambha/core

Requires Node.js 20+.

Pair with @stambha/rest, @stambha/gateway, and @stambha/transform for a full native stack.

Works from ESM (import) and CommonJS (require) — the package ships dual builds (dist/index.js + dist/index.cjs).

import { Command, ok, type CommandContext, type Outcome, type Registry } from "@stambha/core";

CommandContext, Outcome, and other types should use import type when verbatimModuleSyntax is enabled.

---

Quick start

import { Command, createStambhaBot, ok, type CommandContext, type Registry } from "@stambha/core";

class PingCommand extends Command {
  constructor(registry: Registry<Command>) {
    super(registry, { name: "ping", description: "Pong!", kinds: ["prefix"] });
  }

  async execute(ctx: CommandContext) {
    await ctx.reply("Pong!");
    return ok(undefined);
  }
}

const client = createStambhaBot({ prefix: "!" });
client.register(new PingCommand(client.registries.commands));
await client.start();

For production wiring (REST + gateway), see examples/bot.

---

Command pipeline

Inbound events flow through pieces in order:

Conduit → Barrier → Gate → Command → Epilogue

Piece	Folder	Role
Command	commands/	Slash, prefix, context menu handlers
Hook	listeners/	Gateway event listeners
Scout	scouts/	Passive message watchers
Barrier	barriers/	Global command blockers
Gate	gates/	Per-command checks (Sapphire preconditions)
Conduit	conduits/	Middleware before gates
Epilogue	epilogues/	Post-command hooks
Signal	signals/	Buttons, selects, modals (stambha: ids)
Chron	tasks/	Cron scheduled jobs

Auto-load folders with @stambha/loader.

---

Key exports

Export	Purpose
createStambhaBot, StambhaClient	Bot client and lifecycle
Command, Hook, Gate, Scout, …	Piece base classes
ExecutionPipeline	Run conduit → command flow
InboundRouter, SignalRouter	Dispatch commands and components
sequence, SequenceBuilder	Multi-step UI flows
RestPort, HttpRestPort	Outbound API (tier split)
MockBridge	Testing without Discord
ok, err, Outcome	Typed command results
Binder	Lightweight DI
resolveCommandGates	Validate gateNames after loadPieces

Directive is a deprecated alias for Command.

Registry iteration

Registry is not iterable. List pieces with:

const commands = client.registries.commands.toArray();
// or: [...client.registries.commands.values()]
const ping = client.registries.commands.get("ping");

---

Related packages

Package	Use when
@stambha/rest	Native REST client and worker
@stambha/gateway	Shard hub and event routing
@stambha/loader	Auto-load src/commands/, etc.
@stambha/gates	Built-in permission/cooldown gates
@stambha/plugins	Plugin lifecycle hooks

---

Development

# from repo root
pnpm --filter @stambha/core build
pnpm --filter @stambha/core test

Report issues · CHANGELOG