@seedcord/core 0.1.0-next.6 → 0.1.0-next.7

package/dist/index-Dueqztyy.d.mts

@@ -0,0 +1,142 @@
+import { t as Constructor } from "./basic-D7bDlgSP.mjs";
+import { C as Subscriber, O as SubscriptionKey, y as CoreBase } from "./Plugin-3rlH0uxH.mjs";
+import { APIMessageTopLevelComponent } from "discord-api-types/v10";
+import { EventFrequency } from "@seedcord/types";
+
+//#region src/subscribers/decorators/Subscribe.d.ts
+/**
+ * Options accepted by the `@Subscribe` decorator.
+ */
+interface SubscribeOptions {
+  /**
+   * Frequency: `'once'` or `'on'`.
+   *
+   * @defaultValue `'on'`
+   */
+  readonly frequency?: EventFrequency | undefined;
+}
+/**
+ * Registers a subscriber handler class with a specific subscriber event.
+ *
+ * Associates the decorated class with a subscriber event type for automatic
+ * registration and execution when the subscriber is emitted.
+ *
+ * @typeParam TSubscriber - The subscriber event name to register for
+ * @param subscriber - The subscriber event name to register for
+ * @param options - Options to configure the subscriber handler registration.
+ * @decorator
+ * @example
+ * ```typescript
+ * \@Subscribe('userJoin')
+ * class WelcomeHandler extends Subscriber<'userJoin'> {
+ *   async execute() {
+ *     // Handle user join event
+ *   }
+ * }
+ * ```
+ * @example
+ * ```ts
+ * \@Subscribe('userJoin', { frequency: 'once' })
+ * // or
+ * \@Subscribe('userJoin')
+ * ```
+ */
+declare function Subscribe<TSubscriber extends SubscriptionKey>(subscriber: TSubscriber, options?: SubscribeOptions): <HandlerCtor extends Constructor<Subscriber<TSubscriber, CoreBase>>>(constructor: HandlerCtor) => void;
+//#endregion
+//#region src/subscribers/bases/WebhookSender.d.ts
+/**
+ * A file attached to a webhook report.
+ */
+interface WebhookFile {
+  name: string;
+  description: string;
+  /** A `Buffer` still satisfies this, it extends `Uint8Array`. */
+  data: Uint8Array | string;
+}
+/**
+ * The payload {@link WebhookSender.send} posts.
+ */
+interface WebhookSendOptions {
+  flags: number;
+  username: string;
+  components: readonly {
+    toJSON(): APIMessageTopLevelComponent;
+  }[];
+  files?: readonly WebhookFile[] | undefined;
+}
+/**
+ * Sends component messages to a Discord webhook through `@discordjs/rest`.
+ *
+ * @throws A `SeedcordError` when the url does not carry a webhook id and token.
+ */
+declare class WebhookSender {
+  private readonly rest;
+  private readonly route;
+  constructor(url: string);
+  /**
+   * Fetches the webhook object, sending no message. Returns `missing` on a 404 or 401 from
+   * Discord and `unreachable` on any other failure.
+   */
+  verify(): Promise<'ok' | 'missing' | 'unreachable'>;
+  send(options: WebhookSendOptions): Promise<void>;
+}
+//#endregion
+//#region src/subscribers/bases/WebhookLog.d.ts
+/**
+ * The content a reporter returns from {@link WebhookLog.report}.
+ */
+interface WebhookReport {
+  /** Shown as the webhook message author. Defaults to the reporter's class name. */
+  username?: string;
+  components: readonly {
+    toJSON(): APIMessageTopLevelComponent;
+  }[];
+  files?: readonly WebhookFile[] | undefined;
+}
+/**
+ * Base class for subscribers that deliver their event to a Discord webhook.
+ *
+ * Declare the url's environment variable with `@WebhookUrl` and implement {@link report}. Url
+ * resolution, validation, sender reuse, and sending run in the base. When the variable is unset
+ * the reporter is skipped at registration with a boot warning.
+ *
+ * @typeParam KeyOfSubscribers - The subscription key this reporter receives
+ * @typeParam TCore - The transport's Core
+ */
+declare abstract class WebhookLog<KeyOfSubscribers extends SubscriptionKey, TCore extends CoreBase> extends Subscriber<KeyOfSubscribers, TCore> {
+  private static readonly senders;
+  /** Builds the message for one published event. */
+  abstract report(): WebhookReport | Promise<WebhookReport>;
+  execute(): Promise<void>;
+  /** @internal */
+  static senderFor(url: string): WebhookSender;
+  /** @internal */
+  static envKeyOf(ctor: NewableFunction): string;
+  /** @internal Returns null when the env var is unset, throws when set but malformed. */
+  static urlOf(envKey: string): string | null;
+}
+//#endregion
+//#region src/subscribers/decorators/WebhookUrl.d.ts
+/**
+ * Declares the environment variable a {@link WebhookLog} reporter reads its webhook url from.
+ *
+ * An unset variable disables the reporter with a boot warning. A set but malformed value throws
+ * at boot.
+ *
+ * @param envKey - The environment variable name holding the webhook url
+ * @decorator
+ * @example
+ * ```ts
+ * \@Subscribe('memberBanned')
+ * \@WebhookUrl('BAN_LOG_WEBHOOK_URL')
+ * class BanLog extends WebhookLog<'memberBanned'> {
+ *   report() {
+ *     return { components: [new BanCard(this.data).component] };
+ *   }
+ * }
+ * ```
+ */
+declare function WebhookUrl(envKey: string): <HandlerCtor extends Constructor<WebhookLog<SubscriptionKey, CoreBase>>>(constructor: HandlerCtor) => void;
+//#endregion
+export { Subscribe as a, WebhookFile as i, WebhookLog as n, SubscribeOptions as o, WebhookReport as r, WebhookUrl as t };
+//# sourceMappingURL=index-Dueqztyy.d.mts.map

package/dist/index.cjs

@@ -1,6 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_permissions = require('./permissions-DSW_EZfN.cjs');
+const require_publishDefault = require('./publishDefault-l0NQ-SHo.cjs');
+const require_Silence = require('./Silence-DiP95iwD.cjs');
 const require_phases = require('./phases-C_BGNyVo.cjs');
+const require_subscribers = require('./subscribers-B1G6_LlK.cjs');
 require("reflect-metadata");
 let _seedcord_errors = require("@seedcord/errors");
 let _seedcord_errors_internal = require("@seedcord/errors/internal");
@@ -10,7 +12,7 @@ let _seedcord_utils = require("@seedcord/utils");
 //#region src/decorators/Command.ts
 function RegisterCommand(scope, guilds = []) {
 	return (ctor) => {
-		const existingMeta = Reflect.getOwnMetadata(require_permissions.CommandMetadataKey, ctor);
+		const existingMeta = Reflect.getOwnMetadata(require_publishDefault.CommandMetadataKey, ctor);
 		if (existingMeta) throw new _seedcord_errors_internal.SeedcordError(_seedcord_errors.SeedcordErrorCode.DecoratorCommandAlreadyRegistered, [
 			ctor.name,
 			existingMeta.scope,
@@ -22,7 +24,7 @@ function RegisterCommand(scope, guilds = []) {
 			scope,
 			guilds
 		};
-		Reflect.defineMetadata(require_permissions.CommandMetadataKey, meta, ctor);
+		Reflect.defineMetadata(require_publishDefault.CommandMetadataKey, meta, ctor);
 	};
 }
 
@@ -49,7 +51,7 @@ function RegisterCommand(scope, guilds = []) {
 */
 function SlashRoute(...routes) {
 	return function(constructor) {
-		require_permissions.storeInteractionRoute("slash", routes, constructor);
+		require_Silence.storeInteractionRoute("slash", routes, constructor);
 	};
 }
 /**
@@ -74,7 +76,7 @@ function SlashRoute(...routes) {
 */
 function AutocompleteRoute(...routes) {
 	return function(constructor) {
-		require_permissions.storeInteractionRoute("autocomplete", routes, constructor);
+		require_Silence.storeInteractionRoute("autocomplete", routes, constructor);
 	};
 }
 /**
@@ -100,7 +102,7 @@ function AutocompleteRoute(...routes) {
 */
 function ContextMenuRoute(kind, ...names) {
 	return function(constructor) {
-		require_permissions.storeInteractionRoute(require_permissions.contextMenuRouteOf(kind), names, constructor);
+		require_Silence.storeInteractionRoute(require_Silence.contextMenuRouteOf(kind), names, constructor);
 	};
 }
 /**
@@ -116,7 +118,7 @@ function ContextMenuRoute(kind, ...names) {
 */
 function ButtonRoute(...defs) {
 	return function(constructor) {
-		require_permissions.storeComponentRoute("button", defs, constructor);
+		require_Silence.storeComponentRoute("button", defs, constructor);
 	};
 }
 /**
@@ -132,7 +134,7 @@ function ButtonRoute(...defs) {
 */
 function ModalRoute(...defs) {
 	return function(constructor) {
-		require_permissions.storeComponentRoute("modal", defs, constructor);
+		require_Silence.storeComponentRoute("modal", defs, constructor);
 	};
 }
 /**
@@ -153,7 +155,7 @@ function ModalRoute(...defs) {
 */
 function SelectMenuRoute(type, ...defs) {
 	return function(constructor) {
-		require_permissions.storeComponentRoute(require_permissions.selectMenuRouteOf(type), defs, constructor);
+		require_Silence.storeComponentRoute(require_Silence.selectMenuRouteOf(type), defs, constructor);
 	};
 }
 
@@ -192,10 +194,10 @@ var BaseHandler = class {
 	event;
 	logger;
 	dispatch;
-	constructor(event, core, dispatch) {
+	constructor(event, core, dispatch, channel) {
 		this.core = core;
 		this.event = event;
-		this.logger = new _seedcord_logger.Logger(this.constructor.name);
+		this.logger = new _seedcord_logger.Logger(this.constructor.name, { channel });
 		this.dispatch = dispatch;
 	}
 };
@@ -215,7 +217,7 @@ var RepliableHandler = class extends BaseHandler {
 	sender;
 	routeId;
 	constructor(event, core, dispatch) {
-		super(event, core, dispatch);
+		super(event, core, dispatch, "interactions");
 		this.routeId = dispatch?.routeId ?? this.constructor.name;
 		this.sender = this.buildSender(event, core, this.routeId);
 	}
@@ -278,21 +280,21 @@ var RepliableHandler = class extends BaseHandler {
 * }
 * ```
 */
-var Fault = class extends require_permissions.Notice {
+var Fault = class extends require_Silence.Notice {
 	constructor(options) {
 		super("A fault occurred", options?.cause === void 0 ? void 0 : { cause: options.cause });
 		this.report = options?.report ?? true;
 	}
 	render(ctx) {
-		return { components: [new require_permissions.NoticeCard(`Something went wrong. Please reach out to ${ctx.developerUsername ?? "the developer"} with a way to reproduce the error and the following:\n### UUID: \`${ctx.uuid}\``, "Error").component] };
+		return { components: [new require_Silence.NoticeCard(`Something went wrong. Please reach out to ${ctx.developerUsername ?? "the developer"} with a way to reproduce the error and the following:\n### UUID: \`${ctx.uuid}\``, "Error").component] };
 	}
 };
 
 //#endregion
 //#region src/gates/combinators.ts
 function and(...gates) {
-	return require_permissions.defineGate(gates.map((gate) => gate.name).join(" & "), async (ctx) => {
-		for (const gate of gates) await require_permissions.runCheck(gate, ctx);
+	return require_Silence.defineGate(gates.map((gate) => gate.name).join(" & "), async (ctx) => {
+		for (const gate of gates) await require_Silence.runCheck(gate, ctx);
 	});
 }
 function isOrOptions(arg) {
@@ -302,17 +304,17 @@ function or(...args) {
 	const last = args.at(-1);
 	const options = last !== void 0 && isOrOptions(last) ? last : void 0;
 	const gates = options ? args.slice(0, -1) : args;
-	return require_permissions.defineGate(gates.map((gate) => gate.name).join(" | "), async (ctx) => {
+	return require_Silence.defineGate(gates.map((gate) => gate.name).join(" | "), async (ctx) => {
 		const summaries = [];
 		let everyArmHasSummary = true;
 		for (const gate of gates) {
-			const mark = require_permissions.markCommits(ctx);
+			const mark = require_Silence.markCommits(ctx);
 			try {
-				await require_permissions.runCheck(gate, ctx);
+				await require_Silence.runCheck(gate, ctx);
 				return;
 			} catch (error) {
-				if (error instanceof require_permissions.Notice && !(error instanceof Fault) && !error.report) {
-					require_permissions.rollbackCommits(ctx, mark);
+				if (error instanceof require_Silence.Notice && !(error instanceof Fault) && !error.report) {
+					require_Silence.rollbackCommits(ctx, mark);
 					if (error.summary === void 0) everyArmHasSummary = false;
 					else summaries.push(error.summary);
 					continue;
@@ -321,8 +323,8 @@ function or(...args) {
 			}
 		}
 		if (options) throw typeof options.fail === "function" ? options.fail(ctx) : options.fail;
-		if (everyArmHasSummary && summaries.length > 0) throw new require_permissions.NeedsAny(summaries);
-		throw new require_permissions.NotAllowed();
+		if (everyArmHasSummary && summaries.length > 0) throw new require_Silence.NeedsAny(summaries);
+		throw new require_Silence.NotAllowed();
 	});
 }
 
@@ -355,10 +357,10 @@ function or(...args) {
 * ```
 */
 function OwnerOnly(options) {
-	return require_permissions.defineGate("OwnerOnly", (ctx) => {
+	return require_Silence.defineGate("OwnerOnly", (ctx) => {
 		const owners = ctx.core.config.ownerIds ?? [];
 		if (ctx.userId !== null && owners.includes(ctx.userId)) return;
-		throw require_permissions.pickNotice(options, (message) => new require_permissions.NotOwner(message));
+		throw require_Silence.pickNotice(options, (message) => new require_Silence.NotOwner(message));
 	});
 }
 /**
@@ -384,9 +386,9 @@ function OwnerOnly(options) {
 * ```
 */
 function GuildOnly(options) {
-	return require_permissions.defineGate("GuildOnly", (ctx) => {
+	return require_Silence.defineGate("GuildOnly", (ctx) => {
 		if (ctx.guildId) return;
-		throw require_permissions.pickNotice(options, (message) => new require_permissions.NotInGuild(message));
+		throw require_Silence.pickNotice(options, (message) => new require_Silence.NotInGuild(message));
 	});
 }
 /**
@@ -410,9 +412,9 @@ function GuildOnly(options) {
 * ```
 */
 function DmOnly(options) {
-	return require_permissions.defineGate("DmOnly", (ctx) => {
+	return require_Silence.defineGate("DmOnly", (ctx) => {
 		if (!ctx.guildId) return;
-		throw require_permissions.pickNotice(options, (message) => new require_permissions.NotInDm(message));
+		throw require_Silence.pickNotice(options, (message) => new require_Silence.NotInDm(message));
 	});
 }
 
@@ -484,45 +486,16 @@ function Cooldown(duration, options) {
 	};
 	const anonId = anonSeq++;
 	const keyOf = (ctx) => `cooldown:${ctx.routeId ?? `anon${anonId}`}:${per}:w${windowMs}:l${options?.limit ?? 1}:${scopeValue(ctx, per)}`;
-	return require_permissions.defineEffectGate("Cooldown", async (ctx) => {
+	return require_Silence.defineEffectGate("Cooldown", async (ctx) => {
 		const result = await ctx.core.rateLimiter.peek(keyOf(ctx), window);
 		if (!result.limited) return;
 		if (options?.notice) throw options.notice(result.resetAt);
-		throw new require_permissions.OnCooldown(result.resetAt, options?.message?.(result.resetAt));
+		throw new require_Silence.OnCooldown(result.resetAt, options?.message?.(result.resetAt));
 	}, async (ctx) => {
 		await ctx.core.rateLimiter.charge(keyOf(ctx), window);
 	});
 }
 
-//#endregion
-//#region src/stops/Silence.ts
-/**
-* Throw to stop a handler with no reply and no report.
-*
-* The framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.
-* Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to
-* leave the user with no reply for an interaction.
-*
-* @example
-* ```ts
-* import { Silence } from '@seedcord/gateway';
-*
-* // before any reply or defer, drop the interaction with no reply and no report
-* if (await isBlacklisted(interaction.user.id)) throw new Silence('blacklisted user');
-* ```
-*/
-var Silence = class extends Error {
-	reason;
-	/**
-	* @param reason - Optional note written only to a debug log, never shown to the user or reported.
-	*/
-	constructor(reason) {
-		super(reason ?? "Silence");
-		this.reason = reason;
-		Error.captureStackTrace(this, this.constructor);
-	}
-};
-
 //#endregion
 //#region src/pagination/paginate.ts
 /**
@@ -552,38 +525,43 @@ function paginate(items, page, perPage) {
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.1.0-next.6";
+const version = "0.1.0-next.7";
 
 //#endregion
 exports.AutocompleteRoute = AutocompleteRoute;
 exports.BaseHandler = BaseHandler;
-exports.BuilderComponent = require_permissions.BuilderComponent;
+exports.BuilderComponent = require_publishDefault.BuilderComponent;
+exports.Bus = require_subscribers.Bus;
 exports.ButtonRoute = ButtonRoute;
 exports.ContextMenuRoute = ContextMenuRoute;
 exports.Cooldown = Cooldown;
-exports.CustomId = require_permissions.CustomId;
+exports.CustomId = require_Silence.CustomId;
 exports.DispatchContext = DispatchContext;
 exports.DmOnly = DmOnly;
 exports.Fault = Fault;
 exports.GuildOnly = GuildOnly;
 exports.ModalRoute = ModalRoute;
-exports.Notice = require_permissions.Notice;
+exports.Notice = require_Silence.Notice;
 exports.OwnerOnly = OwnerOnly;
 exports.RegisterCommand = RegisterCommand;
 exports.RepliableHandler = RepliableHandler;
-exports.RequireBotPermissions = require_permissions.RequireBotPermissions;
-exports.RequirePermissions = require_permissions.RequirePermissions;
-exports.RequireRole = require_permissions.RequireRole;
-exports.RowComponent = require_permissions.RowComponent;
-exports.SelectMenuKind = require_permissions.SelectMenuKind;
+exports.RequireBotPermissions = require_Silence.RequireBotPermissions;
+exports.RequirePermissions = require_Silence.RequirePermissions;
+exports.RequireRole = require_Silence.RequireRole;
+exports.RowComponent = require_publishDefault.RowComponent;
+exports.SelectMenuKind = require_Silence.SelectMenuKind;
 exports.SelectMenuRoute = SelectMenuRoute;
 exports.ShutdownPhase = require_phases.ShutdownPhase;
-exports.Silence = Silence;
+exports.Silence = require_Silence.Silence;
 exports.SlashRoute = SlashRoute;
 exports.StartupPhase = require_phases.StartupPhase;
+exports.Subscribe = require_subscribers.Subscribe;
+exports.Subscriber = require_subscribers.Subscriber;
+exports.WebhookLog = require_subscribers.WebhookLog;
+exports.WebhookUrl = require_subscribers.WebhookUrl;
 exports.and = and;
-exports.defineEffectGate = require_permissions.defineEffectGate;
-exports.defineGate = require_permissions.defineGate;
+exports.defineEffectGate = require_Silence.defineEffectGate;
+exports.defineGate = require_Silence.defineGate;
 exports.or = or;
 exports.paginate = paginate;
 exports.version = version;