hood-alerts 0.1.0

package/dist/bot/index.d.ts

@@ -0,0 +1,241 @@
+import { P as Platform } from '../schema-DuDMPqpq.js';
+import { EntitlementGate } from '../tiers/index.js';
+import { A as AlertStore, c as Logger } from '../logger-CYza_0eU.js';
+import { a as TelegramClientOptions, T as TelegramClient } from '../telegram-pvphmBwn.js';
+import { F as FetchLike } from '../types-C0ETog04.js';
+import 'zod';
+import '../types-DFPpTMWo.js';
+import 'viem';
+import 'hoodchain';
+import '../logs-D7sYBvSy.js';
+import '../registry-D3We8Lg6.js';
+import '../ratelimit-CGLlXNIS.js';
+
+/**
+ * The bot's command surface, written once and shared by Telegram and Discord.
+ *
+ * Both platforms deliver the same thing to this router: a command name, a
+ * subscriber id, a default delivery target and a list of arguments. Keeping
+ * the logic here means the two bots cannot drift apart in what `/rule add`
+ * accepts or what `/tier` reports, and it means the command tests exercise the
+ * real code path rather than a Telegram-shaped copy of it.
+ *
+ * Every command answers bad input with a specific, actionable message. There
+ * is no silent failure and no raw validation dump: a mistyped threshold gets
+ * "usd must be a positive number, for example /threshold whales 5000".
+ */
+/** What a platform hands the router. */
+interface CommandContext {
+    /** Stable identity for entitlements: `telegram:<user id>`, `discord:<guild or user id>`. */
+    subscriberId: string;
+    platform: Platform;
+    /**
+     * Where alerts would go if the user does not name a target: the Telegram
+     * chat id, or the Discord channel id the command was used in.
+     */
+    defaultTarget: string;
+    /** Arguments after the command word. */
+    args: string[];
+    /** The whole argument string, for commands that take free-form JSON. */
+    rest: string;
+}
+/** A reply to render back to the user. */
+interface CommandReply {
+    /** Telegram HTML, which Discord renders acceptably after tag stripping. */
+    html: string;
+    /** Plain-text equivalent, used by Discord and by logs. */
+    text: string;
+}
+/** A command the bot exposes. */
+interface CommandSpec {
+    name: string;
+    description: string;
+    /** Usage line shown by `/help` and in the README. */
+    usage: string;
+    /** Discord slash-command options, when the command takes arguments. */
+    options?: {
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+}
+/** Everything the router needs. */
+interface CommandRouterDeps {
+    store: AlertStore;
+    gate: EntitlementGate;
+    /** Clock injection point for tests. @defaultValue `Date.now` */
+    now?: () => number;
+    /** Id factory for new subscriptions and nonces. @defaultValue `randomUUID` */
+    newId?: () => string;
+    /** Shown by `/upgrade`: how to pay. Set from the service config. */
+    upgradeInstructions?: string;
+}
+/** The router. */
+interface CommandRouter {
+    /** Every command, for `/help` and for Discord registration. */
+    readonly commands: readonly CommandSpec[];
+    /** Handle one command. Never throws: errors come back as a reply. */
+    handle(command: string, context: CommandContext): Promise<CommandReply>;
+}
+/** The command catalogue. */
+declare const COMMANDS: readonly CommandSpec[];
+/** Build the command router. */
+declare function createCommandRouter(deps: CommandRouterDeps): CommandRouter;
+
+/**
+ * The Telegram bot: long polling, because it needs no public URL, no TLS
+ * certificate and no inbound firewall rule. A self-hoster runs the container
+ * and the bot works; a webhook deployment would need all three before the
+ * first `/start`.
+ *
+ * `getUpdates` is called with a long timeout, so the loop is idle rather than
+ * busy between messages, and the offset is advanced past every update the loop
+ * has handled so a restart never re-processes an old command.
+ */
+/** Options for {@link createTelegramBot}. */
+interface TelegramBotOptions extends TelegramClientOptions {
+    router: CommandRouter;
+    logger?: Logger;
+    /** Reuse the notifier's client so both share one rate-limit path. */
+    client?: TelegramClient;
+    /** Long-poll timeout in seconds. @defaultValue `30` */
+    pollTimeoutSeconds?: number;
+    /** Persist the update offset so a restart resumes cleanly. */
+    offsetStore?: {
+        get(): number | null;
+        set(offset: number): void;
+    };
+}
+/** A running bot. */
+interface TelegramBot {
+    /** Poll once and handle whatever arrived. Returns how many updates it handled. */
+    pollOnce(): Promise<number>;
+    /** Publish the command list so Telegram shows the `/` menu. */
+    publishCommands(): Promise<boolean>;
+    /** Start the loop. Resolves when {@link TelegramBot.stop} is called. */
+    start(): Promise<void>;
+    /** Stop the loop after the current poll. */
+    stop(): void;
+}
+/**
+ * Build the Telegram bot.
+ *
+ * @example
+ * ```ts
+ * const bot = createTelegramBot({ botToken: process.env.TELEGRAM_BOT_TOKEN!, router })
+ * await bot.publishCommands()
+ * await bot.start()
+ * ```
+ */
+declare function createTelegramBot(options: TelegramBotOptions): TelegramBot;
+
+/**
+ * The Discord bot: slash commands over the HTTP interactions endpoint.
+ *
+ * Discord offers two ways to receive commands: a persistent gateway
+ * WebSocket, or an HTTPS interactions endpoint. This package uses the
+ * endpoint, because the service already runs an HTTP server for `/health` and
+ * `/metrics`, and an endpoint scales to zero and survives a restart with no
+ * reconnect logic. The price is that every request must be signature-verified,
+ * which Discord enforces: it sends deliberately invalid signatures during
+ * setup and refuses to save an endpoint that answers them with anything other
+ * than `401`.
+ *
+ * Verification is Ed25519 over `timestamp + rawBody`, using the application's
+ * public key. Node's `crypto` verifies Ed25519 natively, so this needs no
+ * dependency: the raw 32-byte key is wrapped in the fixed SPKI DER prefix for
+ * `id-Ed25519` (RFC 8410) and handed to `createPublicKey`.
+ */
+/** Discord's interaction type numbers, for the two kinds handled here. */
+declare const INTERACTION_TYPE: {
+    readonly PING: 1;
+    readonly APPLICATION_COMMAND: 2;
+};
+/** Discord's interaction callback types. */
+declare const CALLBACK_TYPE: {
+    readonly PONG: 1;
+    readonly CHANNEL_MESSAGE_WITH_SOURCE: 4;
+};
+/** Discord marks a message ephemeral (only the caller sees it) with this flag. */
+declare const EPHEMERAL_FLAG: number;
+/**
+ * Verify a Discord interaction signature.
+ *
+ * @param publicKey the application's hex public key from the developer portal.
+ * @returns `true` only for a signature that verifies. Any malformed input is
+ * `false`, never a throw: a crash here would answer Discord with a 500 and
+ * fail its endpoint validation just as surely as a wrong answer.
+ */
+declare function verifyDiscordSignature(publicKey: string, signature: string, timestamp: string, rawBody: string): boolean;
+/** A Discord slash-command definition, as the API expects it. */
+interface DiscordCommandDefinition {
+    name: string;
+    description: string;
+    /** Option type 3 is STRING, the only type these commands need. */
+    options?: {
+        type: 3;
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+}
+/** Convert the shared command catalogue into Discord slash-command definitions. */
+declare function discordCommandDefinitions(commands: readonly CommandSpec[]): DiscordCommandDefinition[];
+/** Options for {@link registerDiscordCommands}. */
+interface RegisterCommandsOptions {
+    applicationId: string;
+    botToken: string;
+    /** Register to one guild (instant) instead of globally (up to an hour to propagate). */
+    guildId?: string;
+    apiBase?: string;
+    fetch?: FetchLike;
+}
+/**
+ * Register slash commands with Discord.
+ *
+ * @returns the number of commands Discord accepted.
+ * @throws when Discord rejects the registration, with its own error message
+ * attached: a silent failure here means a bot that appears installed and has
+ * no commands.
+ *
+ * @example
+ * ```bash
+ * DISCORD_APPLICATION_ID=... DISCORD_BOT_TOKEN=... npm run register:discord
+ * ```
+ */
+declare function registerDiscordCommands(commands: readonly CommandSpec[], options: RegisterCommandsOptions): Promise<number>;
+/** What to answer Discord with. */
+interface InteractionResponse {
+    status: number;
+    body: unknown;
+}
+/** Options for {@link createDiscordInteractionHandler}. */
+interface DiscordInteractionOptions {
+    router: CommandRouter;
+    /** The application's public key, for signature verification. */
+    publicKey: string;
+    /** Reply only to the caller. @defaultValue `true` */
+    ephemeral?: boolean;
+}
+/**
+ * Build the interactions handler. Mount it on the service's HTTP server at
+ * whatever path is configured as the application's Interactions Endpoint URL.
+ *
+ * @example
+ * ```ts
+ * const interactions = createDiscordInteractionHandler({ router, publicKey })
+ * // inside the HTTP server:
+ * const answer = await interactions.handle({ signature, timestamp, rawBody })
+ * res.writeHead(answer.status, { 'content-type': 'application/json' })
+ * res.end(JSON.stringify(answer.body))
+ * ```
+ */
+declare function createDiscordInteractionHandler(options: DiscordInteractionOptions): {
+    handle(request: {
+        signature: string | null;
+        timestamp: string | null;
+        rawBody: string;
+    }): Promise<InteractionResponse>;
+};
+
+export { CALLBACK_TYPE, COMMANDS, type CommandContext, type CommandReply, type CommandRouter, type CommandRouterDeps, type CommandSpec, type DiscordCommandDefinition, type DiscordInteractionOptions, EPHEMERAL_FLAG, INTERACTION_TYPE, type InteractionResponse, type RegisterCommandsOptions, type TelegramBot, type TelegramBotOptions, createCommandRouter, createDiscordInteractionHandler, createTelegramBot, discordCommandDefinitions, registerDiscordCommands, verifyDiscordSignature };

package/dist/bot/index.js

@@ -0,0 +1,30 @@
+import "../chunk-ZDM5VNWB.js";
+import {
+  CALLBACK_TYPE,
+  COMMANDS,
+  EPHEMERAL_FLAG,
+  INTERACTION_TYPE,
+  createCommandRouter,
+  createDiscordInteractionHandler,
+  createTelegramBot,
+  discordCommandDefinitions,
+  registerDiscordCommands,
+  verifyDiscordSignature
+} from "../chunk-32GS6XVE.js";
+import "../chunk-NBMINJ5E.js";
+import "../chunk-W2GUAWUR.js";
+import "../chunk-VC5MKEY2.js";
+import "../chunk-3LHCQA4Z.js";
+export {
+  CALLBACK_TYPE,
+  COMMANDS,
+  EPHEMERAL_FLAG,
+  INTERACTION_TYPE,
+  createCommandRouter,
+  createDiscordInteractionHandler,
+  createTelegramBot,
+  discordCommandDefinitions,
+  registerDiscordCommands,
+  verifyDiscordSignature
+};
+//# sourceMappingURL=index.js.map

package/dist/bot/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}