nubis 0.0.0 → 0.1.0-next.0

package/dist/commands.d.ts

@@ -0,0 +1,24 @@
+import { type Server } from "node:http";
+import type { NubisApi } from "@nubisjs/core";
+import { type NubisConfig } from "./config";
+import { type Project } from "./loader";
+import type { RouteOptions } from "./route";
+/** The dispatch options a config asks for, shared by both transports. */
+export declare function routeOptionsFor(config: NubisConfig, api: NubisApi): RouteOptions;
+/** `nubis sync [--global] [--dry-run]` */
+export declare function runSync(cwd: string, args: readonly string[]): Promise<number>;
+/** Serves the project as an Interactions Endpoint URL. Exported for tests. */
+export declare function createHttpServer(options: {
+    readonly publicKey: string;
+    readonly project: Project;
+    readonly config: NubisConfig;
+    readonly api: NubisApi;
+}): Server;
+/** `nubis start`: runs the bot until it's stopped. */
+export declare function runStart(cwd: string): Promise<number>;
+/**
+ * `nubis dev`: syncs commands to the test server and runs the bot, then does
+ * both again whenever a file changes, nubis.config.ts included. Each run is
+ * a fresh process, so edits to helpers are picked up too.
+ */
+export declare function runDev(cwd: string): Promise<number>;

package/dist/config-loader.d.ts

@@ -0,0 +1,10 @@
+import { type NubisConfig } from "./config";
+export interface LoadedConfig {
+    readonly config: NubisConfig;
+    /** The file it came from; undefined when the bot has none. */
+    readonly file: string | undefined;
+    /** Where the bot's folders are: `root` resolved against the config's folder. */
+    readonly root: string;
+}
+/** Loads `nubis.config.*` from `cwd`. A bot without one gets the defaults. */
+export declare function loadConfig(cwd: string): Promise<LoadedConfig>;

package/dist/config.d.ts

@@ -0,0 +1,51 @@
+import type { ErrorHandler, Guard, Middleware } from "@nubisjs/core";
+import { GatewayIntentBits, type GatewayPresenceUpdateData } from "discord-api-types/v10";
+export type IntentName = Exclude<keyof typeof GatewayIntentBits, "GuildBans" | "GuildEmojisAndStickers">;
+export interface PresenceConfig {
+    readonly status?: "online" | "idle" | "dnd" | "invisible";
+    /** What the member list shows under the bot's name. */
+    readonly activity?: {
+        readonly type: "playing" | "listening" | "watching" | "competing" | "custom";
+        /** For "custom", the status text itself. */
+        readonly name: string;
+    };
+}
+/** Settings for the whole bot, in `nubis.config.ts` next to its folders. */
+export interface NubisConfig {
+    /** Where commands/, components/, menus/ and events/ live, relative to the config. */
+    readonly root?: string;
+    /** Intents beyond what the bot's events need, e.g. ["MessageContent"]. */
+    readonly intents?: readonly IntentName[];
+    readonly presence?: PresenceConfig;
+    /** Guards for every command, component, modal and menu. */
+    readonly guards?: readonly Guard[];
+    /** Middleware around every handler. */
+    readonly middleware?: readonly Middleware[];
+    /** Every handler error, after the user has been told. Defaults to logging. */
+    readonly onError?: ErrorHandler;
+    /** See LifecycleOptions.autoDeferMs. */
+    readonly autoDeferMs?: number | false;
+    /**
+     * How `nubis start` talks to Discord: the gateway (default), or an HTTP
+     * endpoint for the Interactions Endpoint URL. HTTP bots get no events.
+     */
+    readonly transport?: "gateway" | "http";
+    readonly http?: {
+        /** Defaults to PORT, then 3000. */
+        readonly port?: number;
+        /** Defaults to "/interactions". */
+        readonly path?: string;
+    };
+    /** The test server for `nubis dev` and `nubis sync`, if not in DISCORD_DEV_GUILD_ID. */
+    readonly devGuildId?: string;
+}
+/** Types a `nubis.config.ts`. An identity function. */
+export declare function defineConfig(config: NubisConfig): NubisConfig;
+/**
+ * Checks a loaded config, so a typo fails at startup with the file and key
+ * named instead of being silently ignored.
+ */
+export declare function validateConfig(config: unknown, file: string): NubisConfig;
+export declare function intentBits(names?: readonly IntentName[]): number;
+/** The gateway's presence payload for a config's `presence`. */
+export declare function presenceData(presence: PresenceConfig | undefined): GatewayPresenceUpdateData | undefined;

package/dist/env.d.ts

@@ -0,0 +1,15 @@
+/** Parses KEY=VALUE lines. Quotes are optional; `#` starts a comment line. */
+export declare function parseEnv(text: string): Record<string, string>;
+/**
+ * Loads the nearest `.env`, looking in `start` and then its parents, into
+ * `target` without overriding what's already set. Returns the file it used.
+ */
+export declare function loadEnv(start: string, target?: Record<string, string | undefined>): Promise<string | undefined>;
+export interface DiscordEnv {
+    readonly token: string;
+    readonly applicationId: string;
+    readonly publicKey: string | undefined;
+    readonly devGuildId: string | undefined;
+}
+/** Reads the DISCORD_* settings, naming any that are missing. */
+export declare function discordEnv(env?: Record<string, string | undefined>): DiscordEnv;

package/dist/http.d.ts

@@ -0,0 +1,41 @@
+import { type APIInteraction } from "discord-api-types/v10";
+import { type InteractionProject, type RouteOptions } from "./route";
+export type { InteractionProject } from "./route";
+export interface InteractionHandlerOptions {
+    /** The application's public key from the Developer Portal (hex). */
+    readonly publicKey: string;
+    readonly project: InteractionProject;
+    /** Guards, middleware and auto-defer settings for every interaction. */
+    readonly dispatch?: RouteOptions;
+    /**
+     * Keeps work alive after the HTTP response is sent (follow-ups, edits).
+     * Serverless platforms provide this, e.g. `ctx.waitUntil` on Workers.
+     */
+    readonly waitUntil?: (work: Promise<unknown>) => void;
+    /** Called once an interaction has been fully handled, for logging. */
+    readonly onResult?: (result: InteractionResult) => void;
+    /** Discord's API base. Defaults to https://discord.com/api/v10. */
+    readonly api?: string;
+    /** Swappable in tests. */
+    readonly fetch?: typeof fetch;
+}
+export type InteractionResult = {
+    readonly interaction: APIInteraction;
+    readonly status: string;
+    readonly error?: unknown;
+};
+/**
+ * Checks Discord's Ed25519 signature on an interaction request. Discord
+ * sends test requests with bad signatures and disables the endpoint if they
+ * aren't rejected, so this must run before anything else.
+ */
+export declare function verifyDiscordRequest(publicKey: string, signature: string, timestamp: string, body: string): Promise<boolean>;
+/**
+ * An HTTP endpoint for Discord's "Interactions Endpoint URL". Takes a web
+ * standard Request and returns a Response, so it runs on Node, Bun, Deno and
+ * serverless platforms alike:
+ *
+ *     const handle = createInteractionHandler({ publicKey, project });
+ *     export default { fetch: handle };
+ */
+export declare function createInteractionHandler(options: InteractionHandlerOptions): (request: Request) => Promise<Response>;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "@nubisjs/core";
+export type { API } from "./api";
+export type { IntentName, NubisConfig, PresenceConfig } from "./config";
+export { defineConfig } from "./config";
+export type { InteractionHandlerOptions, InteractionProject, InteractionResult, } from "./http";
+export { createInteractionHandler, verifyDiscordRequest } from "./http";

package/dist/index.js

@@ -0,0 +1,295 @@
+var __esm = (fn, res, err) => () => {
+  if (fn)
+    try {
+      res = fn(fn = 0);
+    } catch (e) {
+      err = [e];
+    }
+  if (err)
+    throw err[0];
+  return res;
+};
+
+// src/config.ts
+import {
+  ActivityType,
+  GatewayIntentBits,
+  PresenceUpdateStatus
+} from "discord-api-types/v10";
+function defineConfig(config) {
+  return config;
+}
+function validateConfig(config, file) {
+  const where = (detail) => new Error(`${file}: ${detail}`);
+  if (typeof config !== "object" || config === null) {
+    throw where("export the config as default: export default defineConfig({ ... }).");
+  }
+  const value = config;
+  for (const key of Object.keys(value)) {
+    if (!KEYS.has(key)) {
+      throw where(`"${key}" isn't a config setting. The settings are: ${[...KEYS].join(", ")}.`);
+    }
+  }
+  for (const name of value.intents ?? []) {
+    if (typeof name !== "string" || !(name in GatewayIntentBits) || !Number.isNaN(Number(name))) {
+      throw where(`"${String(name)}" isn't an intent. Use names like "MessageContent" or "GuildMembers".`);
+    }
+  }
+  const presence = value.presence;
+  if (presence?.status && !(presence.status in STATUSES)) {
+    throw where(`presence.status must be online, idle, dnd or invisible (got "${presence.status}").`);
+  }
+  if (presence?.activity && !(presence.activity.type in ACTIVITY_TYPES)) {
+    throw where(`presence.activity.type must be playing, listening, watching, competing or custom (got "${presence.activity.type}").`);
+  }
+  if (value.transport !== undefined && value.transport !== "gateway" && value.transport !== "http") {
+    throw where(`transport must be "gateway" or "http" (got "${String(value.transport)}").`);
+  }
+  return value;
+}
+function intentBits(names = []) {
+  return names.reduce((bits, name) => bits | GatewayIntentBits[name], 0);
+}
+function presenceData(presence) {
+  if (!presence)
+    return;
+  const activity = presence.activity;
+  return {
+    since: null,
+    afk: false,
+    status: STATUSES[presence.status ?? "online"] ?? PresenceUpdateStatus.Online,
+    activities: activity ? [
+      activity.type === "custom" ? {
+        type: ActivityType.Custom,
+        name: "Custom Status",
+        state: activity.name
+      } : { type: ACTIVITY_TYPES[activity.type], name: activity.name }
+    ] : []
+  };
+}
+var KEYS, ACTIVITY_TYPES, STATUSES;
+var init_config = __esm(() => {
+  KEYS = new Set([
+    "root",
+    "intents",
+    "presence",
+    "guards",
+    "middleware",
+    "onError",
+    "autoDeferMs",
+    "transport",
+    "http",
+    "devGuildId"
+  ]);
+  ACTIVITY_TYPES = {
+    playing: ActivityType.Playing,
+    listening: ActivityType.Listening,
+    watching: ActivityType.Watching,
+    competing: ActivityType.Competing,
+    custom: ActivityType.Custom
+  };
+  STATUSES = {
+    online: PresenceUpdateStatus.Online,
+    idle: PresenceUpdateStatus.Idle,
+    dnd: PresenceUpdateStatus.DoNotDisturb,
+    invisible: PresenceUpdateStatus.Invisible
+  };
+});
+
+// src/route.ts
+import {
+  dispatch,
+  dispatchAutocomplete,
+  dispatchComponent,
+  dispatchMenu,
+  dispatchModal
+} from "@nubisjs/core";
+import {
+  ApplicationCommandType,
+  InteractionType
+} from "discord-api-types/v10";
+function routeInteraction(project, interaction, transport, options) {
+  switch (interaction.type) {
+    case InteractionType.ApplicationCommand:
+      return interaction.data.type === ApplicationCommandType.ChatInput ? dispatch(project.tree, interaction, transport, options) : dispatchMenu(project.menus, interaction, transport, options);
+    case InteractionType.MessageComponent:
+      return dispatchComponent(project.components, interaction, transport, options);
+    case InteractionType.ApplicationCommandAutocomplete:
+      return dispatchAutocomplete(project.tree, interaction, transport, options);
+    case InteractionType.ModalSubmit:
+      return dispatchModal(project.components, interaction, transport, options);
+    default:
+      return Promise.resolve({ status: "unsupported" });
+  }
+}
+var init_route = () => {};
+
+// src/http.ts
+import { NubisError } from "@nubisjs/core";
+import {
+  InteractionResponseType,
+  InteractionType as InteractionType2
+} from "discord-api-types/v10";
+function importPublicKey(publicKey) {
+  let key = keyCache.get(publicKey);
+  if (!key) {
+    const raw = hexToBytes(publicKey);
+    if (!raw || raw.length !== 32) {
+      throw new NubisError("The public key must be the 64 hex characters shown in the Developer Portal.");
+    }
+    key = crypto.subtle.importKey("raw", raw, { name: "Ed25519" }, false, [
+      "verify"
+    ]);
+    keyCache.set(publicKey, key);
+  }
+  return key;
+}
+async function verifyDiscordRequest(publicKey, signature, timestamp, body) {
+  const signatureBytes = hexToBytes(signature);
+  if (!signatureBytes || signatureBytes.length !== 64)
+    return false;
+  const key = await importPublicKey(publicKey);
+  return crypto.subtle.verify({ name: "Ed25519" }, key, signatureBytes, new TextEncoder().encode(timestamp + body));
+}
+async function discordError(response, what) {
+  const text = await response.text().catch(() => "");
+  let code;
+  try {
+    code = JSON.parse(text).code;
+  } catch {}
+  if (code === INVALID_WEBHOOK_TOKEN || code === UNKNOWN_WEBHOOK || code === UNKNOWN_INTERACTION) {
+    return new NubisError(`${what} failed: the interaction token has expired. Discord allows follow-ups and edits for 15 minutes after an interaction.`);
+  }
+  return new NubisError(`${what} failed: Discord answered ${response.status}${text ? ` ${text.slice(0, 200)}` : ""}.`);
+}
+function requestBody(body, files) {
+  if (body === undefined)
+    return { headers: {} };
+  if (!files?.length) {
+    return {
+      body: JSON.stringify(body),
+      headers: { "content-type": "application/json" }
+    };
+  }
+  const form = new FormData;
+  form.append("payload_json", JSON.stringify(body));
+  files.forEach((file, index) => {
+    const blob = file.data instanceof Blob ? file.data : new Blob([file.data], {
+      type: file.contentType ?? "application/octet-stream"
+    });
+    form.append(`files[${index}]`, blob, file.name);
+  });
+  return { body: form, headers: {} };
+}
+function webhookTransport(options) {
+  const { interaction, api } = options;
+  const webhook = `${api}/webhooks/${interaction.application_id}/${interaction.token}`;
+  const call = async (method, url, what, body, files) => {
+    const request = requestBody(body, files);
+    const response = await options.fetch(url, { method, ...request });
+    if (!response.ok)
+      throw await discordError(response, what);
+  };
+  const editOriginal = (body, files) => call("PATCH", `${webhook}/messages/@original`, "Editing the reply", body, files);
+  return {
+    respond: async (response, files) => {
+      if (files?.length && "data" in response) {
+        const updating = response.type === InteractionResponseType.UpdateMessage;
+        const flags = response.data?.flags;
+        await options.respond(updating ? { type: InteractionResponseType.DeferredMessageUpdate } : {
+          type: InteractionResponseType.DeferredChannelMessageWithSource,
+          data: flags ? { flags } : {}
+        });
+        await editOriginal(response.data, files);
+        return;
+      }
+      await options.respond(response);
+    },
+    editOriginal,
+    deleteOriginal: () => call("DELETE", `${webhook}/messages/@original`, "Deleting the reply"),
+    followUp: (body, files) => call("POST", webhook, "Sending a follow-up", body, files)
+  };
+}
+function createInteractionHandler(options) {
+  const api = options.api ?? DEFAULT_API;
+  const fetcher = options.fetch ?? fetch;
+  importPublicKey(options.publicKey);
+  return async (request) => {
+    if (request.method !== "POST")
+      return new Response(null, { status: 405 });
+    const signature = request.headers.get("x-signature-ed25519");
+    const timestamp = request.headers.get("x-signature-timestamp");
+    const body = await request.text();
+    if (!signature || !timestamp || !await verifyDiscordRequest(options.publicKey, signature, timestamp, body)) {
+      return new Response("Bad request signature", { status: 401 });
+    }
+    const interaction = JSON.parse(body);
+    if (interaction.type === InteractionType2.Ping) {
+      return json({ type: InteractionResponseType.Pong });
+    }
+    let answered = false;
+    let answer = () => {};
+    const initial = new Promise((resolve) => {
+      answer = resolve;
+    });
+    const transport = webhookTransport({
+      interaction,
+      api,
+      fetch: fetcher,
+      respond: async (response) => {
+        if (!answered) {
+          answered = true;
+          answer(response);
+          return;
+        }
+        const callback = await fetcher(`${api}/interactions/${interaction.id}/${interaction.token}/callback`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(response)
+        });
+        if (!callback.ok)
+          throw await discordError(callback, "Responding");
+      }
+    });
+    const work = routeInteraction(options.project, interaction, transport, options.dispatch ?? {}).catch((error) => ({ status: "error", error })).then((result) => {
+      options.onResult?.({ interaction, ...result });
+      return result;
+    });
+    options.waitUntil?.(work);
+    const first = await Promise.race([initial, work.then(() => {
+      return;
+    })]);
+    if (first === undefined) {
+      answered = true;
+      return json({ error: "The handler finished without responding." }, 500);
+    }
+    return json(first);
+  };
+}
+var DEFAULT_API = "https://discord.com/api/v10", hexToBytes = (hex) => {
+  if (hex.length % 2 !== 0 || /[^0-9a-f]/i.test(hex))
+    return;
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0;i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}, keyCache, UNKNOWN_INTERACTION = 10062, UNKNOWN_WEBHOOK = 10015, INVALID_WEBHOOK_TOKEN = 50027, json = (body, status = 200) => new Response(JSON.stringify(body), {
+  status,
+  headers: { "content-type": "application/json" }
+});
+var init_http = __esm(() => {
+  init_route();
+  keyCache = new Map;
+});
+
+// src/index.ts
+init_config();
+init_http();
+
+export * from "@nubisjs/core";
+export {
+  createInteractionHandler,
+  defineConfig,
+  verifyDiscordRequest
+};

package/dist/intents.d.ts

@@ -0,0 +1,11 @@
+import type { EventRegistry } from "@nubisjs/core";
+/** Intents Discord makes you switch on in the Developer Portal first. */
+export declare const PRIVILEGED_INTENTS: number;
+/**
+ * The intents a bot needs for the events it listens to, plus any extra it
+ * asks for (MessageContent, for instance, is never added automatically).
+ * Interactions need no intent at all.
+ */
+export declare function intentsFor(events: EventRegistry, extra?: number): number;
+/** Readable names for a bit field, for logs and errors. */
+export declare function intentNames(intents: number): string[];

package/dist/loader.d.ts

@@ -0,0 +1,33 @@
+import { type CommandTree, type ComponentRegistry, type EventRegistry, type MenuDefinition } from "@nubisjs/core";
+/** Everything a bot is made of, read from its folders. */
+export interface Project {
+    readonly root: string;
+    readonly tree: CommandTree;
+    readonly components: ComponentRegistry;
+    readonly menus: readonly MenuDefinition[];
+    readonly events: EventRegistry;
+    /** Every module that was loaded, relative to `root`, for watching and messages. */
+    readonly files: readonly string[];
+}
+export interface LoadOptions {
+    /** File extensions to load. Defaults to .ts, .mts, .js and .mjs. */
+    readonly extensions?: readonly string[];
+    /**
+     * Appended to import URLs so a changed file is imported fresh, for hot
+     * reload. Leave it out to use the module cache.
+     */
+    readonly version?: string | number;
+}
+/**
+ * Loads a bot from its folders:
+ *
+ * - `commands/` — one command per file, `export default command(...)`.
+ *   Folders become subcommands; `_folder.ts` sets a folder's description,
+ *   guards and permissions.
+ * - `components/` — buttons, selects and modals; every export that is one.
+ * - `menus/` — right-click commands, `export default userCommand(...)`.
+ * - `events/` — `export default event(...)`, or an array of them.
+ *
+ * Files starting with `_`, tests and `.d.ts` files are skipped.
+ */
+export declare function loadProject(root: string, options?: LoadOptions): Promise<Project>;

package/dist/node-listener.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * Adapts a fetch-style handler (`Request` in, `Response` out) to a
+ * `node:http` listener:
+ *
+ *     createServer(toNodeListener(createInteractionHandler({ ... }))).listen(3000);
+ */
+export declare function toNodeListener(handler: (request: Request) => Promise<Response>): (request: IncomingMessage, response: ServerResponse) => void;

package/dist/node.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Node and Bun only: reading a bot from disk. Kept out of the main `nubis`
+ * entry so code that imports `nubis` can still be bundled for edge runtimes.
+ */
+export type { LoadOptions, Project } from "./loader";
+export { loadProject } from "./loader";
+export { toNodeListener } from "./node-listener";
+export type { Bot, BotOptions, GatewayLike } from "./bot";
+export { createBot } from "./bot";
+export { intentBits, presenceData, validateConfig } from "./config";
+export type { LoadedConfig } from "./config-loader";
+export { loadConfig } from "./config-loader";
+export type { DiscordEnv } from "./env";
+export { discordEnv, loadEnv, parseEnv } from "./env";
+export { intentNames, intentsFor, PRIVILEGED_INTENTS } from "./intents";
+export type { RestLike } from "./rest-transport";
+export { restTransport } from "./rest-transport";
+export type { SyncOptions, SyncResult } from "./sync";
+export { describePlan, hasChanges, syncCommands } from "./sync";