@stambha/rest

Native Discord REST client — centralized rate-limit queue, split-tier REST worker, and slash command deploy. No discord.js in the REST process.

Part of the @stambha monorepo · GitHub · Tier split docs

Install

npm install @stambha/rest @stambha/core @stambha/transport

Requires Node.js 20+.

Quick start

In-process REST (monolith)

import { createStambhaBot } from "@stambha/core";
import { createNativeRestPort } from "@stambha/rest";

const token = process.env.DISCORD_TOKEN!;

const client = createStambhaBot({
  restPort: createNativeRestPort(token),
});

Commands call ctx.reply() through the shared RestPort — rate limits are handled globally.

Standalone REST worker (tier split)

import { createNativeRestWorker } from "@stambha/rest";

const { url, close } = await createNativeRestWorker({
  token: process.env.DISCORD_TOKEN!,
  port: 4000,
});

console.log(`REST worker listening at ${url}`);

Point the bot worker at it with HttpRestPort from @stambha/core (REST_WORKER_URL in examples/bot).

Deploy slash commands

import {
  deployCommands,
  deployCommandsIfShardZero,
  formatDeployDiff,
  shouldDeploySlashCommands,
} from "@stambha/rest";

// Shard 0 only when sharded — see docs/deployment/slash-deploy.md
if (shouldDeploySlashCommands({ shardId: 0 })) {
  const result = await deployCommands({
    token: process.env.DISCORD_TOKEN!,
    applicationId: process.env.DISCORD_APPLICATION_ID!,
    commands: client.registries.commands.values(),
    diff: true,
  });
  if (result.diff) console.log(formatDeployDiff(result.diff));
}

CI dry-run: pnpm --filter @stambha/example-bot deploy:dry-run

Resource helpers (0.3.4+)

Thin wrappers over RestPort.request for common bot operations — no discord.js required:

import { fetchUser, fetchGuildMember, sendChannelMessage } from "@stambha/rest";

const user = await fetchUser(client.restPort!, userId);
await sendChannelMessage(client.restPort!, channelId, {
  embeds: [{ title: "Hello" }],
});

Use with defineArgResolver from @stambha/args when you need REST-backed entity parsing.

Key exports

| Export | Purpose | |--------|---------| | createNativeRestPort | RestPort for in-process REST | | RestClient, createRestClient | Low-level Discord API client | | RateLimitQueue | Per-route bucket queue | | createNativeRestWorker | HTTP REST worker process | | deployCommands | Register application commands | | deployCommandsIfShardZero | Deploy only on shard 0 | | shouldDeploySlashCommands | Guard for multi-process sharding | | formatDeployDiff | Log diff summary | | fetchUser, fetchGuild, fetchGuildMember, … | Common REST resource helpers | | createRestTelemetryListener | Hook metrics into the queue |

Related packages

| Package | Role | |---------|------| | @stambha/core | RestPort, HttpRestPort, command contexts | | @stambha/transport | API version, session, route keys | | @stambha/metrics | Prometheus REST telemetry |

Development

pnpm --filter @stambha/rest build
pnpm --filter @stambha/rest test