@seedcord/http 0.10.2 → 0.11.0-next.0

package/README.md

@@ -10,7 +10,7 @@
   <a href="https://seedcord.org">Website</a> ·
   <a href="https://seedcord.org/guide">Guide</a> ·
   <a href="https://seedcord.org/docs">Reference</a> ·
-  <a href="https://discord.gg/DzFxY58WXf">Discord</a>
+  <a href="https://seedcord.org/chat/">Discord</a>
 </div>
 
 <br />
@@ -23,22 +23,68 @@
 
 ## About
 
-`@seedcord/http` runs a seedcord bot on Discord's interactions endpoint. Discord posts each interaction to your URL. The framework verifies the Ed25519 signature before dispatching it.
+`@seedcord/http` is the transport for an http bot. Discord posts each interaction to your bot's URL, and the bot checks the request's Ed25519 signature before it runs your handler. It has no discord.js dependency and keeps no connection open, so it runs on your own server or on Cloudflare Workers.
 
-Discord posts only interactions over this transport. Use [`@seedcord/gateway`](https://www.npmjs.com/package/@seedcord/gateway) when the bot reacts to messages, members, or voice.
+Discord posts only interactions to that URL. Use [`@seedcord/gateway`](https://www.npmjs.com/package/@seedcord/gateway) when your bot reacts to messages, members, voice, or reactions.
 
-Until v1.0.0, minor versions can break.
+seedcord is pre-1.0, so a minor version can break your bot. Each release's changelog says what changed and how to update.
 
 ## Installation
 
+`pnpm create seedcord` sets up a new bot and asks where it runs. To add seedcord to an existing project:
+
 ```sh
-pnpm add @seedcord/http
+pnpm add @seedcord/http @discordjs/builders envapt
+pnpm add -D seedcord vite typescript
 ```
 
-`pnpm create seedcord` scaffolds the whole project. On this transport `pnpm dev` also opens a cloudflared tunnel and registers the URL with Discord.
+`envapt` and `typescript` are peer dependencies. `seedcord` is the CLI that runs the bot in dev and builds it. In dev, it also opens a cloudflared tunnel and sets your app's interactions URL to it.
+
+## Usage
+
+`bot.ts` creates the bot and tells it where your handlers are:
+
+```ts
+import { Seedcord } from '@seedcord/http';
+import { Converters, Envapter } from 'envapt';
+
+export default new Seedcord({
+    bot: {
+        interactions: { path: './handlers' },
+        commands: {
+            path: './commands',
+            guilds: Envapter.getAs('TESTING_GUILD_IDS', Converters.array(), [])
+        }
+    },
+    subscribers: { path: null }
+});
+```
+
+Read your environment through [envapt](https://envapt.materwelon.dev), the way `TESTING_GUILD_IDS` is read above. seedcord loads your `.env` files into envapt, and binds a worker's `env` to it on Cloudflare Workers, so the same read works in dev, in a build, and on Workers. envapt also reads your shell's variables, while `process.env` misses everything in your `.env` files.
+
+Handlers read raw payloads from `discord-api-types`. Slash commands, components, checks, and plugins work the same way as on the gateway. The [guide](https://seedcord.org/guide) covers them.
+
+## Where it runs
 
-## Entry points
+### Its own server
+
+On Node or Bun, `Seedcord` listens on `port`, 3000 by default.
+
+### Inside your server
+
+Set `port: false`, start the bot, then pass each request to `bot.fetch()`. It takes a web `Request` and returns a `Response`, so a Hono or Next.js route can forward to it:
+
+```ts
+import { Hono } from 'hono';
+
+import bot from './bot';
+
+await bot.start();
+
+const app = new Hono();
+app.post('/interactions', (c) => bot.fetch(c.req.raw));
+```
 
-The root entry runs on Node through the `Seedcord` class.
+### Cloudflare Workers
 
-`@seedcord/http/edge` targets Web-standard runtimes through `createSeedcord`. The Node entry re-exports all of it. The edge build for Cloudflare Workers is a work in progress and cannot be used yet.
+The same `Seedcord` import runs on Cloudflare Workers. A `cloudflare.config.ts` beside `seedcord.config.ts` makes `seedcord build` write a worker, which you deploy with `cf deploy --prebuilt`. The [Workers guide](https://seedcord.org/guide/build/workers) covers the setup.

package/dist/index.d.mts

@@ -1,91 +1,76 @@
-import { S as EngineContext, _ as InjectedEmojiMap, a as CursorSource, b as SlashOptions, c as PageContext, d as ModalHandler, f as ButtonHandler, g as Emojis, h as SlashHandler, i as ArraySource, l as Subscriber, m as UserContextMenuHandler, n as Gated, o as PageSource, p as MessageContextMenuHandler, r as InteractionGateContext, s as Paginator, t as version, u as WebhookLog, v as ModalFields, x as createSeedcord, y as SelectedMentionables } from "./edge.index-DFszgCJp.mjs";
-import { _ as Core, a as RoleMenuHandler, b as HttpServerConfig, c as UserMenuHandler, d as RepliableHandler, g as AutocompleteHandler, h as SentMessage, i as MentionableMenuHandler, l as ComponentHandler, m as ReplySender, n as InteractionMiddleware, o as SelectMenuHandler, p as InteractionRef, r as ChannelMenuHandler, s as StringMenuHandler, t as Manifest, u as InteractionHandler, v as HttpConfig, y as HttpEdgeConfig } from "./Manifest-D5MEsTmH.mjs";
-import "reflect-metadata";
-import { REST } from "@discordjs/rest";
+import { A as RoleMenuHandler, B as AutocompleteHandler, C as Plugin, D as InteractionMiddleware, E as EngineContext, F as InteractionHandler, H as HttpConfig, I as RepliableHandler, L as InteractionRef, M as StringMenuHandler, N as UserMenuHandler, O as ChannelMenuHandler, P as ComponentHandler, R as ReplySender, S as HttpPluginOptions, T as PluginOptions, U as HttpEdgeConfig, V as Core, W as HttpServerConfig, _ as Emojis, a as ArraySource, b as SelectedMentionables, c as Paginator, d as WebhookLog, f as ModalHandler, g as SlashHandler, h as UserContextMenuHandler, i as InteractionGateContext, j as SelectMenuHandler, k as MentionableMenuHandler, l as PageContext, m as MessageContextMenuHandler, n as version, o as CursorSource, p as ButtonHandler, r as Gated, s as PageSource, t as HmrModuleHandler, u as Subscriber, v as InjectedEmojiMap, w as PluginLifecycleSpec, x as SlashOptions, y as ModalFields, z as SentMessage } from "./shared-vsj1uwIH.mjs";
 import { Bus } from "@seedcord/core";
-import { Pluggable } from "@seedcord/core/node";
+import { ServerHost } from "@seedcord/core/node";
+import { HostAugmentTarget, HostListenHost, HostVersion, SeedcordBrand, SeedcordInstance } from "@seedcord/types/internal";
+import { REST } from "@discordjs/rest";
 import { WinstonConsoleSink, WinstonFileSink } from "@seedcord/logger/node";
-import { HostAugmentTarget, HostVersion, SeedcordBrand, SeedcordInstance } from "@seedcord/types/internal";
-import { Plugin as Plugin$1, PluginLifecycleSpec, PluginOptions, PluginOptions as PluginOptions$1 } from "@seedcord/core/plugin";
-import { IRateLimiter, TypedOmit } from "@seedcord/types";
-export * from "@seedcord/logger";
-export * from "@seedcord/core";
+import { IRateLimiter } from "@seedcord/types";
 export * from "@seedcord/errors";
-export * from "@seedcord/rate-limiter";
+export * from "@seedcord/core";
+export * from "@seedcord/logger";
 export * from "@seedcord/event-emitter";
+export * from "@seedcord/rate-limiter";
 export * from "@seedcord/utils";
 export * from "@seedcord/types";
 //#region src/node/Seedcord.d.ts
-type RuntimeOfConfig<Cfg extends HttpConfig> = Cfg extends {
-  runtime: 'edge';
-} ? 'edge' : 'server';
 /**
- * The HTTP-interactions bot host, a long-running node server around the engine.
+ * The HTTP-interactions bot on node. `start()` loads handlers from `config.bot.interactions.path`
+ * and binds a server on `port`. With `port: false`, your own server passes requests to `fetch()`.
  *
- * Discovers handlers from `config.bot.interactions.path`, verifies and dispatches interactions on
- * `start()`, and runs coordinated shutdown with an in-flight drain. The edge deploy path calls
- * `createSeedcord` from a generated entry.
+ * Shutdown waits up to 5s for interactions that are still running.
  */
-export declare class Seedcord<Cfg extends HttpConfig = HttpConfig> extends Pluggable<'http', RuntimeOfConfig<Cfg>> implements SeedcordInstance {
+export declare class Seedcord extends ServerHost<'http'> implements SeedcordInstance {
+  #private;
   /** @internal */
   readonly [SeedcordBrand] = true;
   /** @internal */
   readonly [HostAugmentTarget] = "@seedcord/http";
   /** @internal */
   readonly [HostVersion]: string;
+  /** @internal */
+  [HostListenHost]?: string | undefined;
   /** Discord REST client built from `bot.restOptions`. `start()` sets the token. */
   readonly rest: REST;
   /** @see {@link IRateLimiter} */
   readonly rateLimiter: IRateLimiter;
   /** @see {@link Bus} */
   readonly bus: Bus;
-  private readonly subscribers;
-  private readonly interactions?;
-  private readonly commandRegistry?;
-  private readonly emojiInjector;
-  private readonly hmrManager;
-  private readonly logger;
-  private token?;
-  private server?;
-  private boundPort?;
-  private fetchedUsername?;
-  readonly config: HttpConfig;
-  constructor(config: Cfg);
+  readonly config: HttpServerConfig;
+  /**
+   * @throws A **SeedcordError** when another `Seedcord` exists in this process and has not shut down.
+   * @throws A **SeedcordError** when the running Node or Bun is older than the range in `engines`.
+   */
+  constructor(config: HttpServerConfig);
   /** The bot's discord username, populated by the ready fetch. */
   get username(): string | undefined;
-  /** The bound server port, populated once `start()` is listening. */
+  /** The bound server port, set once `start()` is listening. Stays `undefined` with `port: false`. */
   get port(): number | undefined;
   /**
    * Starts the host and runs the startup tasks.
    */
   start(): Promise<this>;
-  protected static reset(host?: object): boolean;
-  private registerStartupTasks;
-  private registerHmrAwareModules;
-  private authenticate;
+  /**
+   * Answers one request to the interactions endpoint. Mount it in your own server when the
+   * config sets `port: false`.
+   *
+   * Rejects with `CoreFetchBeforeStart` until `start()` is called. A request that arrives while
+   * `start()` runs waits for all of startup, the command deploy included. Answers 503 once
+   * shutdown begins or `start()` fails.
+   *
+   * @example
+   * ```ts
+   * // Hono passes the untouched request through c.req.raw
+   * const seedcord = new Seedcord({ ...config, port: false });
+   * await seedcord.start();
+   *
+   * const app = new Hono();
+   * app.post('/interactions', (c) => seedcord.fetch(c.req.raw));
+   * ```
+   */
+  fetch(request: Request): Promise<Response>;
   /** The bot's Discord application id. Throws if you read it before the Configuration phase. */
   get applicationId(): string;
-  private listen;
-  private fetchUsername;
-  private stopServer;
 }
 //#endregion
-//#region src/Plugin.d.ts
-/** The options an HTTP plugin declares, narrowed to the transports this base serves. */
-type HttpPluginOptions = TypedOmit<PluginOptions$1, 'transport'> & {
-  transport?: 'http';
-};
-/**
- * Base class for an HTTP plugin, binding `this.core` to the HTTP {@link Core}.
- *
- * A plugin that runs on either transport extends the base from `@seedcord/core/plugin`, whose
- * `this.core` is typed to the shared members only.
- *
- * @typeParam Opts - The transport and runtime the plugin declares.
- */
-export declare abstract class Plugin<Opts extends HttpPluginOptions = {
-  transport: 'http';
-}> extends Plugin$1<Opts, Core> {}
-//#endregion
-export { ArraySource, AutocompleteHandler, ButtonHandler, ChannelMenuHandler, ComponentHandler, type Core, CursorSource, Emojis, type EngineContext, Gated, type HttpConfig, type HttpEdgeConfig, type HttpPluginOptions, type HttpServerConfig, type InjectedEmojiMap, type InteractionGateContext, InteractionHandler, InteractionMiddleware, type InteractionRef, type Manifest, MentionableMenuHandler, MessageContextMenuHandler, ModalFields, ModalHandler, type PageContext, type PageSource, Paginator, type PluginLifecycleSpec, type PluginOptions, RepliableHandler, ReplySender, RoleMenuHandler, SelectMenuHandler, type SelectedMentionables, type SentMessage, SlashHandler, type SlashOptions, StringMenuHandler, Subscriber, UserContextMenuHandler, UserMenuHandler, WebhookLog, WinstonConsoleSink, WinstonFileSink, createSeedcord, version };
+export { ArraySource, AutocompleteHandler, ButtonHandler, ChannelMenuHandler, ComponentHandler, type Core, CursorSource, Emojis, type EngineContext, Gated, HmrModuleHandler, type HttpConfig, type HttpEdgeConfig, type HttpPluginOptions, type HttpServerConfig, type InjectedEmojiMap, type InteractionGateContext, InteractionHandler, InteractionMiddleware, type InteractionRef, MentionableMenuHandler, MessageContextMenuHandler, ModalFields, ModalHandler, type PageContext, type PageSource, Paginator, Plugin, type PluginLifecycleSpec, type PluginOptions, RepliableHandler, ReplySender, RoleMenuHandler, SelectMenuHandler, type SelectedMentionables, type SentMessage, SlashHandler, type SlashOptions, StringMenuHandler, Subscriber, UserContextMenuHandler, UserMenuHandler, WebhookLog, WinstonConsoleSink, WinstonFileSink, version };
 //# sourceMappingURL=index.d.mts.map