Rin is a WhatsApp command service built with Zapo and TypeScript. It provides decorator-based command registration, dependency injection, and persistent SQLite session storage.
- Bun 1.4 or later
- A WhatsApp account that can be linked as a companion device
- Linux x64 or ARM64 to use
!sticker; its native conversion worker is distributed for those platforms.
bun install
cp .env.example .envConfigure the following values in .env as needed:
| Variable | Default | Description |
|---|---|---|
BOT_PREFIX |
! |
Prefix required for command messages. |
BOT_LOG_LEVEL |
info |
Minimum severity for application logs. |
BOT_SESSION_ID |
rin |
Identifier for the Zapo session. |
BOT_AUTH_PATH |
.auth/state.sqlite |
SQLite file for credentials and Signal state. |
BOT_PAIRING_PHONE |
unset | Optional international phone number for code-based pairing. |
BOT_SUPERUSER_ID |
unset | Owner phone number only; no @s.whatsapp.net or @lid. |
BOT_ROLE_DB_PATH |
.auth/roles.sqlite |
SQLite database for superuser-managed moderators. |
BOT_MODERATION_DB_PATH |
.auth/moderation.sqlite |
SQLite database for per-group moderation settings. |
TYPESAFE_API_KEY |
unset | Authorizes Jev requests; groups enable filtering separately. |
TYPESAFE_MODEL |
jev-1.14.0 |
Jev model used for moderation. |
BOT_BADWORD_THRESHOLD |
0.9 |
Probability threshold used to flag a rule violation (0–1). |
bun run devOn an unpaired session, one of the following methods is used:
- QR pairing (default): In WhatsApp, open Settings → Linked devices → Link a device, then scan the QR code shown in the terminal.
- Phone-number pairing: Set
BOT_PAIRING_PHONEto a digits-only international phone number, for example628123456789. The terminal displays an eight-character code. In WhatsApp, select Linked devices → Link with phone number instead and enter the code.
Session credentials are stored at the configured BOT_AUTH_PATH. Keep this file
private; it is excluded from version control.
| Command | Description |
|---|---|
!help |
Lists registered commands. |
!ping |
Verifies that the service is responding. |
!sticker (!s) |
Converts a supported image or video attached to, or quoted by, the command (up to 16 MiB). |
!group (!gc) |
Lets group admins manage the current group. |
!group is available to group admins (and the configured superuser) in the
current group. It supports adding, removing, promoting, and demoting members;
changing the subject or description; controlling announcement-only and
restricted-info modes; viewing or rotating the invite link; and viewing basic
group details. Supply a phone number or WhatsApp JID to add a member; use a
WhatsApp mention for other member actions. Run !group without an action to
see its usage.
!group link-sharing off restricts forwarding or sharing the group invite link
to admins.
To use Jev moderation, configure TYPESAFE_API_KEY, then have a group admin
run !group filter on in each group. The API key only authorizes requests; it
does not activate filtering globally. Built-in moderation flags messages that
contain a profane, obscene, or hateful slur. Group admins can add additional
policy with !group filter requirement add <rule>, list rules with ... requirement list, remove one with ... requirement remove <id>, or remove all
custom rules with ... requirement clear.
TypeSafe receives message text or captions, the text of each configured custom
rule, and eligible image bytes for classification. Eligible images are
non-view-once JPEG or PNG attachments no larger than 8 MiB. Image moderation
uses an experimental capability; tune BOT_BADWORD_THRESHOLD on representative
messages before relying on it for high-stakes moderation.
The threshold determines whether Jev flags a violation. Deleting a flagged message also requires the bot to be a group admin and a successful WhatsApp revoke operation. If a TypeSafe request fails or times out, the message is allowed (fail open); do not use this filter as the sole safety control.
For each flagged message, the bot attempts a warning reply. Use !group filter warnings <count> to enable automatic member-removal attempts after that many
warnings; for example, !group filter warnings 3 attempts removal on a
member's third warning. Automatic removal is disabled by default and can be
turned off with !group filter warnings off. Reset a member's warning count
with !group filter warnings reset <@mention>. Member removal also requires
bot admin privileges and a successful WhatsApp operation. The bot keeps group
metadata cached, refreshes it after group changes it makes, and refreshes it
when WhatsApp reports a group lifecycle event.
bun run format # Format project files
bun run format:check # Validate formatting
bun run lint # Run static analysis
bun run typecheck # Type-check without emitting files
bun run verify # Run type-checking and all Biome checksBiome enforces two-space indentation and the recommended TypeScript lint rules.
The GitHub Actions workflow runs bun run verify for every push and pull
request.
Use @/ for imports from src/; for example,
@/framework/core/di.ts resolves to src/framework/core/di.ts. Keep relative
imports for modules in the same directory.
src/framework/ contains the reusable bot runtime: the command router,
decorators and contracts, DI container, WhatsApp integration, configuration,
and shared services. src/app/ is application-owned code: commands, feature
services, and the composition bootstrap.
Commands are autoloaded from src/app/commands/**/*.command.ts at startup.
The filename convention deliberately excludes *.test.ts, so a new command
only needs its own decorated module—there is no central imports file to edit.
Create a decorated command class under src/app/commands, for example
src/app/commands/echo.command.ts:
import { Command } from '@/framework/commands/command.decorator.ts';
import { Injectable } from '@/framework/core/di.ts';
import type {
BotCommand,
CommandContext,
} from '@/framework/commands/contracts.ts';
@Command({
name: 'echo',
description: 'Return the supplied text.',
})
@Injectable()
export class EchoCommand implements BotCommand {
async execute({ args, reply }: CommandContext): Promise<void> {
await reply(args.join(' ') || 'No text was supplied.');
}
}The module is registered automatically at startup. Use
@Injectable([Dependency]) to declare dependencies resolved by the application
container.
@Injectable() services are singletons by default. The container also supports
typed symbol tokens, factories, transient services, and request/job scopes:
import { Container, createToken, Injectable } from '@/framework/core/di.ts';
const container = new Container();
interface Clock {
now(): number;
}
const CLOCK = createToken<Clock>('Clock');
const REQUEST_ID = createToken<string>('RequestId');
@Injectable()
class SystemClock implements Clock {
now(): number {
return Date.now();
}
}
@Injectable({
dependencies: [CLOCK, REQUEST_ID],
lifetime: 'scoped',
})
class RequestState {
constructor(
readonly clock: Clock,
readonly requestId: string,
) {}
}
container
.registerSingleton(CLOCK, SystemClock)
.registerFactory(REQUEST_ID, () => crypto.randomUUID(), 'scoped');
const scope = container.createScope();
try {
const state = scope.resolve(RequestState);
console.log(state.clock.now(), state.requestId);
} finally {
await scope.dispose();
}registerTransient creates an instance for every resolution; registerScoped
shares an instance within a scope. A singleton cannot consume a scoped service,
including through transient services, which prevents leaking request state. All
container-managed lifecycle services are disposed when their owning scope or the
root container is disposed. Values passed to registerValue remain
caller-owned.
Container-managed services can implement standard AsyncDisposable to release
resources:
@Injectable()
export class CacheClient implements AsyncDisposable {
async [Symbol.asyncDispose](): Promise<void> {
await this.close();
}
}The container invokes [Symbol.asyncDispose]() (or synchronous
[Symbol.dispose]()), once in reverse creation order when an owner is
disposed. bootstrap() disposes the container if initialization fails and
handles SIGINT, SIGTERM, and normal event-loop shutdown through
beforeExit. It continues disposing remaining services if an earlier callback
fails.
Permissions are decorators, separate from command registration:
@GroupAdmin(), @Moderator(), and @Superuser(). Apply them to command
classes or command-group subcommand methods. Commands without a permission
decorator are public. @Superuser() requires the single numeric
BOT_SUPERUSER_ID; @Moderator() requires an entry in the moderator database
(or the superuser); and @GroupAdmin() is available to WhatsApp group admins
only (or the superuser). Group-admin checks fetch current group metadata, and
therefore are denied if WhatsApp cannot be reached to verify the role.
The superuser maintains moderator assignments with !cardinal addmod,
!cardinal delmod, and !cardinal mods. Add and remove commands accept a phone
number, a WhatsApp user JID, or a WhatsApp @mention.
The superuser can also run administrative terminal and debugging commands:
!cardinal console <shell command>
!cardinal debug <JavaScript expression or statements>
@Command({ name: 'purge', description: 'Remove recent messages.' })
@GroupAdmin()For policies beyond those built-in roles, add @Require(...) (or its
@Check(...) alias). A check receives the sender, parsed message, arguments,
and lazy role resolvers. It can be synchronous or asynchronous, and can be
packaged into a reusable decorator in the same style as discord.py checks:
import { Command, Require } from '@/framework/commands/command.decorator.ts';
const InAllowedGroup = (groupJid: string) =>
Require((authorization) => {
if (authorization.event.key.remoteJid === groupJid) return true;
return { allowed: false, reason: 'allowed_group_required' };
});
@Command({ name: 'announce', description: 'Send an announcement.' })
@Moderator()
@InAllowedGroup('123456789@g.us')
@Injectable()
export class AnnounceCommand implements BotCommand {
async execute(context: CommandContext): Promise<void> {
// ...
}
}Multiple checks are combined with AND semantics and run after the built-in
permission decorator. Checks may call authorization.isBotModerator() or
authorization.isGroupAdmin() when needed. Returning false, returning
{ allowed: false, reason }, or throwing denies execution; a thrown error
fails closed and is logged. The configured superuser remains able to run every
command, including commands with custom checks.
Use @Group(...) on a DI-managed command class, then put @Command(...) on
its methods. This follows Discord.Net’s group/module style while keeping the
current TypeScript decorator and OOP model:
import { Injectable } from '@/framework/core/di.ts';
import {
Command,
Group,
GroupAdmin,
} from '@/framework/commands/command.decorator.ts';
import type {
BotCommand,
CommandContext,
} from '@/framework/commands/contracts.ts';
@Group({
name: 'poll',
aliases: ['vote'],
description: 'Manage polls in this group.',
})
@GroupAdmin()
@Injectable()
export class PollCommand implements BotCommand {
// Called for `!poll` or an unknown subcommand.
async execute(context: CommandContext): Promise<void> {
await context.reply(`Usage: ${context.prefix}poll create|close`);
}
@Command({
name: 'create',
aliases: ['new'],
description: 'Create a poll.',
})
async create(context: CommandContext): Promise<void> {
// For `!poll create Best snack?`, this is ["Best", "snack?"].
await context.reply(`Creating a poll: ${context.args.join(' ')}`);
}
@Command({
name: 'close',
description: 'Close the active poll.',
})
async close(context: CommandContext): Promise<void> {
// ...
}
}Group permissions and custom checks apply to every subcommand. A permission,
check, or cooldown placed on a subcommand method applies in addition to the
group’s authorization; a subcommand cooldown overrides a group cooldown.
!help lists top-level commands and groups without exposing their subcommands.
Use @Cooldown(milliseconds) to limit each sender's executions of a command.
Cooldowns are in-memory, begin after authorization succeeds but before the
command runs, and reset if the bot restarts:
import { Command, Cooldown } from '@/framework/commands/command.decorator.ts';
@Command({ name: 'render', description: 'Render an image.' })
@Cooldown(30_000)
@Injectable()
export class RenderCommand implements BotCommand {
async execute(context: CommandContext): Promise<void> {
// ...
}
}The same sender may still run different commands; a command on cooldown replies with the remaining wait time.
Rin is licensed under the GNU General Public License v3.0 only. See LICENSE.