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

package/dist/Plugin-BZit5HUI.d.mts

@@ -0,0 +1,555 @@
+import { FrameworkChannel, Logger } from "@seedcord/logger";
+import { TypedEventEmitter } from "@seedcord/event-emitter";
+import { REST } from "@discordjs/rest";
+import { Config, EventFrequency, HmrAware, HmrUpdateEvent, IRateLimiter, RenderContext, ReplyResponse, Tail, TypedExclude } from "@seedcord/types";
+import { UUID } from "node:crypto";
+
+//#region src/metadataKeys.d.ts
+declare enum InteractionRoutes {
+  Slash = "slash",
+  Button = "button",
+  Modal = "modal",
+  StringMenu = "stringMenu",
+  UserMenu = "userMenu",
+  RoleMenu = "roleMenu",
+  ChannelMenu = "channelMenu",
+  MentionableMenu = "mentionableMenu",
+  MessageContextMenu = "messageContextMenu",
+  UserContextMenu = "userContextMenu",
+  Autocomplete = "autocomplete"
+}
+declare const InteractionMetadataKey: unique symbol;
+declare const InteractionRouteKeys: Record<InteractionRoutes, symbol>;
+declare const MiddlewareMetadataKey: unique symbol;
+declare const EventMetadataKey: unique symbol;
+declare const CommandMetadataKey: unique symbol;
+declare const GatedMetadataKey: unique symbol;
+declare const SubscribeMetadataKey: unique symbol;
+declare const WebhookUrlMetadataKey: unique symbol;
+//#endregion
+//#region src/subscribers/publishDefault.d.ts
+/**
+ * The key of the Bus method that emits the framework's own subscriptions. `publish` excludes these keys
+ * through `PublishableKey`, and this symbol is exported only from the internal entry.
+ *
+ * @internal
+ */
+declare const PublishDefault: unique symbol;
+//#endregion
+//#region src/reply/AckTrace.d.ts
+/** The first ack's stack, passed as the throw cause so a double-ack points to both lines. */
+declare class AckTrace extends Error {
+  constructor(method: ReplyMethod);
+}
+//#endregion
+//#region src/reply/ackLegality.d.ts
+type AckState = 'unacked' | 'deferred-reply' | 'deferred-update' | 'replied';
+type ReplyMethod = 'reply' | 'defer' | 'deferUpdate' | 'update' | 'followUp' | 'edit' | 'delete' | 'send' | 'showModal';
+/** Throws before any API call. `ackedBy` becomes the throw cause, its stack points at the first ack. */
+declare function checkAckLegality(method: ReplyMethod, state: AckState, routeId: string, ackedBy?: AckTrace): void;
+declare function sendTarget(state: AckState): 'reply' | 'edit' | 'followUp';
+//#endregion
+//#region src/reply/responseReport.d.ts
+/** What `publishResponse` requires. Without it the call returns without publishing. */
+interface ReplyTelemetry {
+  readonly bus: Bus;
+  readonly interactionId: string;
+}
+/** The reply verbs plus the autocomplete choices callback, which runs outside the ack state machine. */
+type WriteMethod = ReplyMethod | 'respond';
+/**
+ * Runs a write that returns no message and publishes whichever arm it takes.
+ *
+ * @internal
+ */
+declare function reportedWrite<Result>(telemetry: ReplyTelemetry | undefined, routeId: string, method: WriteMethod, write: () => Promise<Result>): Promise<Result>;
+//#endregion
+//#region src/stops/Notice.d.ts
+/**
+ * Base class for a user-facing refusal or a reported fault.
+ *
+ * Throw a `Notice` to stop a handler and reply to the user. The framework catches it at the controller
+ * boundary and renders {@link Notice.render}, which always decides what the user sees. With `report`
+ * false that render is all that happens. With `report` true the framework also logs the fault and
+ * publishes it to the `handledException` bus. A raw, non-Notice throw shows the generic message.
+ *
+ * @example
+ * ```ts
+ * import { Notice, BuilderComponent, type RenderContext, type ReplyResponse } from '@seedcord/gateway';
+ * import { TextDisplayBuilder } from '@discordjs/builders';
+ *
+ * // reading `.component` applies the configured bot color to the container accent
+ * class TooPoorCard extends BuilderComponent<'container'> {
+ *     constructor(balance: number) {
+ *         super('container');
+ *         this.instance.addTextDisplayComponents(
+ *             new TextDisplayBuilder().setContent(`### Insufficient balance\nYou need more than ${balance} coins.`)
+ *         );
+ *     }
+ * }
+ *
+ * class TooPoor extends Notice {
+ *     constructor(private readonly balance: number) {
+ *         super(`balance ${balance} is below the cost`);
+ *     }
+ *
+ *     render(_ctx: RenderContext): ReplyResponse {
+ *         return { components: [new TooPoorCard(this.balance).component] };
+ *     }
+ * }
+ *
+ * // in a handler, throwing stops the handler and replies with render(ctx)
+ * if (wallet.balance < cost) throw new TooPoor(wallet.balance);
+ * ```
+ */
+declare abstract class Notice extends Error {
+  /**
+   * Whether this denial is a reported fault. True also logs it and publishes it to the `handledException`
+   * bus. The user always sees {@link Notice.render} either way.
+   *
+   * @defaultValue `false`
+   */
+  report: boolean;
+  /**
+   * Whether the reply is ephemeral, so only the invoking user sees it. Set it false for a refusal the
+   * whole channel should see.
+   *
+   * @defaultValue `true`
+   */
+  ephemeral: boolean;
+  /**
+   * A short one-line reason. When every arm of an `or` gate refuses and each refusal sets this, `or`
+   * lists them instead of showing a neutral message.
+   */
+  summary?: string;
+  protected constructor(message: string, options?: ErrorOptions);
+  /**
+   * Builds what the user sees. Called fresh each time the denial is shown, so the builders are new
+   * and the bot color resolves at render time rather than at construction time.
+   */
+  abstract render(ctx: RenderContext): ReplyResponse;
+}
+//#endregion
+//#region src/subscribers/types/Subscriptions.d.ts
+/**
+ * How a dispatch finished. The thrown value's type sets this, wherever it was thrown. A `Silence` and a
+ * `Notice` with `report` false are `refused`. A `Notice` with `report` true, which includes a default
+ * `Fault`, is `failed`, as is any other throw.
+ */
+type DispatchOutcome = 'handled' | 'refused' | 'failed';
+/** Whether a write through the reply surface reached Discord. */
+type ResponseOutcome = 'sent' | 'failed';
+/**
+ * Where a reported fault came from.
+ */
+type FaultSource = InteractionFaultSource | EventFaultSource;
+/**
+ * A fault that came from a discord interaction, JSON-safe for a webhook payload.
+ */
+interface InteractionFaultSource {
+  kind: 'interaction';
+  interactionKind: 'slash' | 'context-menu' | 'button' | 'select' | 'modal';
+  /** Slash or context-menu command name, null for component and modal interactions. */
+  command: string | null;
+  /** Component or modal customId, null for slash and context-menu interactions. */
+  customId: string | null;
+  userId: string;
+  /** Guild the interaction came from, null in DMs. */
+  guildId: string | null;
+  /** Channel the interaction came from, null when unavailable. */
+  channelId: string | null;
+  interactionId: string;
+  /** The raw interaction, made JSON-safe at serialization with filterCirculars. */
+  raw: unknown;
+}
+/**
+ * A fault that came from a client event, JSON-safe for a webhook payload. The actor, guild, and channel
+ * are best-effort, derived from the event args, so each is nullable. The raw args carry the full detail.
+ */
+interface EventFaultSource {
+  kind: 'event';
+  eventName: string;
+  handler: string;
+  userId: string | null;
+  /** Null outside a guild. */
+  guildId: string | null;
+  channelId: string | null;
+  /** The raw event args, made JSON-safe at serialization with filterCirculars. */
+  raw: unknown;
+}
+/**
+ * The framework's own subscription keys. A transport adds a key whose payload type references a type
+ * outside this package, through declaration merging on its own module.
+ *
+ * Every key here is publish-protected. Subscribe to them. The framework is the
+ * only publisher.
+ */
+interface DefaultSubscriptions {
+  /** Triggered when an unhandled exception (a raw non-Notice throw) occurs. */
+  unknownException: {
+    uuid: UUID;
+    error: Error;
+    guild?: {
+      id: string;
+      name: string;
+    } | undefined;
+    user?: {
+      id: string;
+      username: string;
+    } | undefined;
+    metadata?: unknown;
+  };
+  /** Triggered when a reported Notice (`report: true`) is caught. */
+  handledException: {
+    denial: Notice;
+    uuid: UUID;
+    source: FaultSource;
+  };
+  /** Triggered when an interaction dispatch throws past the fault boundary. */
+  unhandledInteractionError: {
+    error: Error;
+  };
+  /** Triggered once per interaction dispatch, after the handler chain settles. */
+  interactionDispatched: {
+    routeId: string; /** The interaction this dispatch ran, for joining against `responseAttempted`. */
+    interactionId: string;
+    kind: `${InteractionRoutes}`;
+    outcome: DispatchOutcome; /** True when no route matched and the unhandled default ran. */
+    fallback: boolean; /** Dispatch entry until the user has a response, replies included. A clock change never affects it. */
+    durationMs: number;
+    /**
+     * Discord's interaction creation until dispatch entry, read from the snowflake. This covers
+     * network transit plus any time your bot was busy before starting, so a rise points at either
+     * Discord or your own backlog. It subtracts a Discord timestamp from the host clock, so a host
+     * running behind Discord reports a negative value.
+     */
+    queuedMs: number;
+  };
+  /**
+   * Triggered on every write through the reply surface, several times per interaction. A write that
+   * throws reports here too, with `outcome` `failed`. A write that reaches Discord and then returns an
+   * unexpected shape publishes nothing, since the callback succeeded and carries no message to name.
+   */
+  responseAttempted: {
+    routeId: string; /** The interaction this write belongs to, for joining against `interactionDispatched`. */
+    interactionId: string; /** `send` routes to another verb, so it reports the verb that ran. */
+    method: WriteMethod;
+    outcome: ResponseOutcome;
+    durationMs: number; /** Null for every ack-only or choice-only verb, and for a failed write. */
+    messageId: string | null; /** Present when `outcome` is `failed`. */
+    error?: Error;
+  };
+}
+/**
+ * Custom subscribers defined by the application. Augment it via declaration merging to type your
+ * own subscriber payloads.
+ *
+ * @example
+ * ```typescript
+ * // the transport package your bot installs, '@seedcord/gateway' or '@seedcord/http'
+ * declare module '@seedcord/gateway' {
+ *   interface Subscriptions {
+ *     'userJoin': { userId: string; guildId: string };
+ *     'levelUp': { userId: string; level: number };
+ *   }
+ * }
+ * ```
+ */
+interface Subscriptions {}
+interface AllSubscriptions extends DefaultSubscriptions, Subscriptions {}
+/** All subscriber event names available to subscribe to and augment. */
+type SubscriptionKey = keyof AllSubscriptions;
+/**
+ * The keys `publish` accepts. The framework's own keys are excluded, since only the framework
+ * produces them.
+ */
+type PublishableKey = TypedExclude<SubscriptionKey, keyof DefaultSubscriptions>;
+/**
+ * The payload type for a subscriber event.
+ *
+ * @typeParam KeyOfSubscribers - The subscriber event name
+ */
+type SubscriptionData<KeyOfSubscribers extends SubscriptionKey> = AllSubscriptions[KeyOfSubscribers];
+type SubscriptionTuples = { [K in SubscriptionKey]: [AllSubscriptions[K]] };
+//#endregion
+//#region src/subscribers/Subscriber.d.ts
+/**
+ * Abstract base class for handling application subscribers.
+ *
+ * Provides type-safe access to subscribers data and the core framework instance.
+ * Extend this class to create custom subscriber handlers.
+ *
+ * @typeParam KeyOfSubscribers - The specific subscriber type this handler processes
+ * @typeParam TCore - The transport's Core
+ */
+declare abstract class Subscriber<KeyOfSubscribers extends SubscriptionKey, TCore extends CoreBase> {
+  protected readonly data: AllSubscriptions[KeyOfSubscribers];
+  protected readonly core: TCore;
+  protected readonly logger: Logger;
+  /**
+   * Instantiates the subscriber with event data and core.
+   *
+   * @param data - The subscriber event data
+   * @param core - The core framework instance
+   */
+  constructor(data: AllSubscriptions[KeyOfSubscribers], core: TCore);
+  /**
+   * Executes the subscriber handler logic.
+   */
+  abstract execute(): Promise<void>;
+}
+//#endregion
+//#region src/subscribers/Bus.d.ts
+/**
+ * A subscriber class as the Bus stores it. Both parameters are `never` because construct-signature
+ * parameters check contravariantly, and a concrete subscriber narrows each to its own payload and
+ * transport `Core`. One cast at dispatch restores both.
+ *
+ * @internal
+ */
+type StoredSubscriberCtor = new (data: never, core: never) => Subscriber<SubscriptionKey, CoreBase>;
+/**
+ * One registration. `resolve` is lazy so an edge host registers from a manifest row without
+ * importing the module until that key first publishes.
+ *
+ * @internal
+ */
+interface SubscriberRegistration {
+  readonly keys: readonly SubscriptionKey[];
+  readonly frequency: EventFrequency;
+  readonly resolve: () => StoredSubscriberCtor | Promise<StoredSubscriberCtor>;
+  /** The resolved class. A server-host registration carries it from the start, a lazy one fills it on first resolve. */
+  ctor?: StoredSubscriberCtor | undefined;
+}
+/**
+ * Registers and dispatches subscribers. Subscribers run on a programmatic or framework publish.
+ * Accessed via `core.bus`. Do not construct it directly.
+ */
+declare class Bus extends TypedEventEmitter<SubscriptionTuples> {
+  protected core: CoreBase;
+  /** @internal */
+  readonly logger: Logger;
+  private readonly subscribersMap;
+  private readonly executedOnce;
+  private readonly webhookProbes;
+  constructor(core: CoreBase);
+  /**
+   * Registers the two shipped webhook reporters. The host calls this during startup, keeping the
+   * url validation inside `start()` where a failure can still release the singleton guard.
+   *
+   * @internal
+   */
+  registerDefaults(): void;
+  /** @internal */
+  register(registration: SubscriberRegistration): void;
+  /** @internal */
+  unregister(ctor: StoredSubscriberCtor, keys?: readonly SubscriptionKey[]): void;
+  /** @internal */
+  get registeredCount(): number;
+  /** @internal Only eagerly registered reporters are probed, which is every server-host one. */
+  verifyWebhooks(): Promise<void>;
+  /** Returns whether the class should register. */
+  private probeWebhook;
+  /**
+   * Publishes an event to its subscribers and native listeners.
+   *
+   * Fire-and-forget, so subscriber handlers run asynchronously and this returns before they
+   * complete, and callers must not assume side effects have completed. Errors thrown by a subscriber
+   * or by an `on()` listener are caught and logged, never surfaced here. One throwing listener
+   * does not stop the others. Subscribers on one key run concurrently and carry no ordering
+   * guarantee. A `'once'` subscriber is marked as executed when it starts (even if it throws), so
+   * it never runs twice.
+   *
+   * The framework's own keys are excluded. Subscribe to those and listen with `on`. The framework
+   * is their only publisher.
+   *
+   * @param event - The subscription key to publish
+   * @param data - Payload passed to each subscriber
+   * @returns Whether the underlying emitter had native listeners for the event
+   */
+  publish<KeyOfSubscribers extends PublishableKey>(event: KeyOfSubscribers, data: AllSubscriptions[KeyOfSubscribers]): boolean;
+  /** @internal the framework's own publish path, keyed by a symbol no public entry exports */
+  [PublishDefault]<KeyOfSubscribers extends keyof DefaultSubscriptions>(event: KeyOfSubscribers, data: AllSubscriptions[KeyOfSubscribers]): boolean;
+  private dispatchKey;
+  protected onListenerError(error: unknown, event: string | symbol): void;
+  private processSubscriber;
+  private runSubscriber;
+}
+//#endregion
+//#region src/interfaces/CoreBase.d.ts
+/**
+ * The transport-agnostic slice of the running framework, what core code (gates, notices, plugins'
+ * agnostic surface) accesses through `ctx.core`. Each transport's `Core` extends it with its own
+ * members.
+ */
+interface CoreBase {
+  /** Transports narrow this to their own config type. */
+  readonly config: Config;
+  /**
+   * Discord REST client. On gateway this is the discord.js client's own, and it carries no token
+   * until the Login phase. On http the token is set by `start()`.
+   */
+  readonly rest: REST;
+  /** Sliding-window rate limiting, the `Cooldown` gate's backend and a public direct-use API. */
+  readonly rateLimiter: IRateLimiter;
+  /** Publish and subscribe to framework and application events. */
+  readonly bus: Bus;
+}
+//#endregion
+//#region src/lifecycle/phases.d.ts
+/**
+ * Startup phases, in run order.
+ */
+declare enum StartupPhase {
+  /** Nothing connected. Plugin init runs here by default. */
+  Configuration = 1,
+  /** The gateway session opens, and http runs its REST-only startup work. */
+  Login = 2,
+  /** Handlers are live and interactions dispatch. */
+  Ready = 3
+}
+/**
+ * Shutdown phases, in run order.
+ */
+declare enum ShutdownPhase {
+  /** Stop taking new interactions and requests. */
+  Unbind = 1,
+  /** Waits for in-flight work to settle and stops internal services. */
+  Drain = 2,
+  /** External resources close. Plugin dispose runs here by default. */
+  Disconnect = 3,
+  /** The client disconnects last so in-flight handlers can still reference it during drain. */
+  Logout = 4
+}
+//#endregion
+//#region src/plugin/lifecycle.d.ts
+/**
+ * The lifecycle a plugin declares through `super(host, spec)`. Unset fields resolve to the base
+ * defaults. `ready` runs at a fixed `StartupPhase.Ready`, so it takes only a timeout.
+ */
+interface PluginLifecycleSpec {
+  init?: {
+    phase?: StartupPhase;
+    timeout?: number;
+  };
+  ready?: {
+    timeout?: number;
+  };
+  dispose?: {
+    phase?: ShutdownPhase;
+    timeout?: number;
+  };
+}
+/** @internal */
+interface ResolvedPluginLifecycleSpec {
+  readonly init: {
+    readonly phase: StartupPhase;
+    readonly timeout: number;
+  };
+  readonly ready: {
+    readonly timeout: number;
+  };
+  readonly dispose: {
+    readonly phase: ShutdownPhase;
+    readonly timeout: number;
+  };
+}
+//#endregion
+//#region src/plugin/options.d.ts
+/** The options a plugin declares as its `Plugin<Opts>` type argument. */
+interface PluginOptions {
+  /**
+   * Which transport the plugin runs on. `'any'` attaches to either one.
+   * @defaultValue 'any'
+   */
+  transport?: 'gateway' | 'http' | 'any';
+  /**
+   * Which runtime the plugin runs on. `'any'` attaches to either one.
+   * @defaultValue 'any'
+   */
+  runtime?: 'server' | 'edge' | 'any';
+}
+/** @internal */
+type TransportOf<Opts extends PluginOptions> = undefined extends Opts['transport'] ? 'any' : NonNullable<Opts['transport']>;
+/** @internal */
+type RuntimeOf<Opts extends PluginOptions> = undefined extends Opts['runtime'] ? 'any' : NonNullable<Opts['runtime']>;
+/** @internal the transport a bot runs */
+type Transport = TypedExclude<NonNullable<PluginOptions['transport']>, 'any'>;
+/** @internal the runtime a bot runs */
+type Runtime = TypedExclude<NonNullable<PluginOptions['runtime']>, 'any'>;
+type TransportMismatch<PluginT extends string, BotT extends string> = Record<`this plugin declares transport '${PluginT}' but this bot runs '${BotT}'`, never>;
+type RuntimeMismatch<PluginRt extends string, BotRt extends string> = Record<`this plugin declares runtime '${PluginRt}' but this bot runs '${BotRt}'`, never>;
+type EdgePluginsUnsupported = Record<'an edge bot takes no plugins until edge support ships after v1', never>;
+/** @internal */
+type ChannelKeyAssert<Key extends string> = Key extends FrameworkChannel ? `'${Key}' is a channel the framework logs on. Pick another plugin key.` : Key;
+type BrandTransport<Plug> = Plug extends {
+  readonly __transport?: infer T extends string;
+} ? T : 'any';
+type BrandRuntime<Plug> = Plug extends {
+  readonly __runtime?: infer R extends string;
+} ? R : 'any';
+/** @internal */
+type TransportAssert<Plug, BotT extends Transport> = BrandTransport<Plug> extends 'any' | BotT ? unknown : TransportMismatch<BrandTransport<Plug>, BotT>;
+/** @internal */
+type RuntimeAssert<Plug, BotRt extends Runtime> = 'edge' extends BotRt ? EdgePluginsUnsupported : BrandRuntime<Plug> extends 'any' | BotRt ? unknown : RuntimeMismatch<BrandRuntime<Plug>, BotRt>;
+//#endregion
+//#region src/plugin/Plugin.d.ts
+interface Initializeable {
+  init(): Promise<void>;
+}
+/** @internal */
+declare const resolvedSpecSlot: unique symbol;
+/**
+ * Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,
+ * implements `init()`, and reads the framework surface through `this.core`.
+ *
+ * @typeParam Opts - The plugin's declared {@link PluginOptions}.
+ * @typeParam TCore - The host type `this.core` resolves to. Each transport binds it to its own `Core`.
+ */
+declare abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase> implements Initializeable, HmrAware {
+  private readonly host;
+  /** @internal phantom, never set at runtime */
+  readonly __transport?: TransportOf<Opts>;
+  /** @internal phantom, never set at runtime */
+  readonly __runtime?: RuntimeOf<Opts>;
+  /** @internal */
+  readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;
+  /** Logs under the plugin's class name, on the channel its attach key sets. */
+  readonly logger: Logger;
+  constructor(host: CoreBase, spec?: PluginLifecycleSpec);
+  /** The host, typed to the transport whose `Plugin` base this class extends. */
+  protected get core(): TCore;
+  abstract init(): Promise<void>;
+  /**
+   * Runs in the startup Ready phase, after `init()`. The gateway client is logged in by this phase,
+   * and the http host runs its server-bind and health tasks in the same phase.
+   */
+  ready?(): Promise<void>;
+  /** Runs during teardown, only when `init()` resolved. */
+  dispose?(): Promise<void>;
+  /**
+   * Throws a `SeedcordError` that contains the plugin class name and the reason.
+   *
+   * @param reason - Why the options are invalid.
+   */
+  protected rejectOptions(reason: string): never;
+  /** Override to reload plugin state on an HMR update. */
+  onHmr(_event: HmrUpdateEvent): Promise<void>;
+  /**
+   * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.
+   * @param patterns - Glob patterns relative to the project root
+   */
+  protected registerCriticalFiles(patterns: string[]): void;
+}
+/** @internal */
+type PluginLike = Pick<Plugin, 'init' | 'ready' | 'dispose' | 'logger' | 'onHmr' | typeof resolvedSpecSlot>;
+/** @internal */
+type PluginCtor<TPlugin extends PluginLike = PluginLike> = new (...args: any[]) => TPlugin;
+/** @internal */
+type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;
+type CoreParamTooNarrow = Record<'this plugin constructor must take CoreBase as its first parameter and read the transport Core off this.core', never>;
+/** @internal */
+type CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0] ? unknown : CoreParamTooNarrow;
+//#endregion
+export { AckState as A, InteractionRouteKeys as B, FaultSource as C, Notice as D, Subscriptions as E, PublishDefault as F, MiddlewareMetadataKey as H, CommandMetadataKey as I, EventMetadataKey as L, checkAckLegality as M, sendTarget as N, ReplyTelemetry as O, AckTrace as P, GatedMetadataKey as R, DispatchOutcome as S, SubscriptionKey as T, SubscribeMetadataKey as U, InteractionRoutes as V, WebhookUrlMetadataKey as W, Bus as _, PluginCtor as a, Subscriber as b, PluginOptions as c, Transport as d, TransportAssert as f, CoreBase as g, StartupPhase as h, PluginArgs as i, ReplyMethod as j, reportedWrite as k, Runtime as l, ShutdownPhase as m, Initializeable as n, PluginLike as o, PluginLifecycleSpec as p, Plugin as r, ChannelKeyAssert as s, CoreParamAssert as t, RuntimeAssert as u, StoredSubscriberCtor as v, SubscriptionData as w, DefaultSubscriptions as x, SubscriberRegistration as y, InteractionMetadataKey as z };
+//# sourceMappingURL=Plugin-BZit5HUI.d.mts.map

package/dist/{Plugin-C2-VHrsX.cjs → Plugin-BlkhHNRm.cjs}

@@ -1,23 +1,9 @@
-const require_phases = require('./phases-C_BGNyVo.cjs');
+const require_phases = require('./phases-DcuDHoQl.cjs');
 const require_devChannel = require('./devChannel-CoCmAVDx.cjs');
+let _seedcord_logger = require("@seedcord/logger");
 let _seedcord_errors = require("@seedcord/errors");
 let _seedcord_errors_internal = require("@seedcord/errors/internal");
 
-//#region src/plugin/context.ts
-/** @internal unset until attach installs the built ctx */
-const pluginContextSlot = Symbol("seedcord.plugin.ctx");
-/** @internal */
-function readPluginContext(holder) {
-	const ctx = holder[pluginContextSlot];
-	if (!ctx) throw new _seedcord_errors_internal.SeedcordError(_seedcord_errors.SeedcordErrorCode.PluginContextBeforeInit, [holder.constructor.name]);
-	return ctx;
-}
-/** @internal */
-function finalizePluginContext(holder, ctx) {
-	holder[pluginContextSlot] = ctx;
-}
-
-//#endregion
 //#region src/plugin/lifecycle.ts
 const DEFAULT_INIT_TIMEOUT_MS = 15e3;
 const DEFAULT_READY_TIMEOUT_MS = 15e3;
@@ -48,27 +34,28 @@ function resolveLifecycleSpec(spec, pluginName) {
 const resolvedSpecSlot = Symbol("seedcord.plugin.spec");
 /**
 * Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,
-* implements `init()`, and reads the framework surface through `this.ctx`.
+* implements `init()`, and reads the framework surface through `this.core`.
 *
 * @typeParam Opts - The plugin's declared {@link PluginOptions}.
+* @typeParam TCore - The host type `this.core` resolves to. Each transport binds it to its own `Core`.
 */
 var Plugin = class {
-	pluggable;
+	host;
 	/** @internal */
 	[resolvedSpecSlot];
-	/** @internal */
-	[pluginContextSlot];
-	constructor(pluggable, spec) {
-		this.pluggable = pluggable;
+	/** Logs under the plugin's class name, on the channel its attach key sets. */
+	logger;
+	constructor(host, spec) {
+		this.host = host;
+		this.logger = new _seedcord_logger.Logger(this.constructor.name);
 		this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);
 	}
-	/** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */
-	get ctx() {
-		return readPluginContext(this);
+	/** The host, typed to the transport whose `Plugin` base this class extends. */
+	get core() {
+		return this.host;
 	}
 	/**
-	* Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the
-	* plugin class and the reason.
+	* Throws a `SeedcordError` that contains the plugin class name and the reason.
 	*
 	* @param reason - Why the options are invalid.
 	*/
@@ -99,16 +86,10 @@ Object.defineProperty(exports, 'Plugin', {
     return Plugin;
   }
 });
-Object.defineProperty(exports, 'finalizePluginContext', {
-  enumerable: true,
-  get: function () {
-    return finalizePluginContext;
-  }
-});
 Object.defineProperty(exports, 'resolvedLifecycleSpecOf', {
   enumerable: true,
   get: function () {
     return resolvedLifecycleSpecOf;
   }
 });
-//# sourceMappingURL=Plugin-C2-VHrsX.cjs.map
+//# sourceMappingURL=Plugin-BlkhHNRm.cjs.map

package/dist/Plugin-BlkhHNRm.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-BlkhHNRm.cjs","names":["SeedcordError","SeedcordErrorCode","Logger","SeedcordError","SeedcordErrorCode"],"sources":["../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts"],"sourcesContent":["import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\nimport { ShutdownPhase, StartupPhase } from '@src/lifecycle/phases';\n\n/**\n * The lifecycle a plugin declares through `super(host, spec)`. Unset fields resolve to the base\n * defaults. `ready` runs at a fixed `StartupPhase.Ready`, so it takes only a timeout.\n */\nexport interface PluginLifecycleSpec {\n    init?: { phase?: StartupPhase; timeout?: number };\n    ready?: { timeout?: number };\n    dispose?: { phase?: ShutdownPhase; timeout?: number };\n}\n\n/** @internal */\nexport interface ResolvedPluginLifecycleSpec {\n    readonly init: { readonly phase: StartupPhase; readonly timeout: number };\n    readonly ready: { readonly timeout: number };\n    readonly dispose: { readonly phase: ShutdownPhase; readonly timeout: number };\n}\n\nconst DEFAULT_INIT_TIMEOUT_MS = 15_000;\nconst DEFAULT_READY_TIMEOUT_MS = 15_000;\nconst DEFAULT_DISPOSE_TIMEOUT_MS = 10_000;\n\nfunction timeoutOf(\n    field: 'init' | 'ready' | 'dispose',\n    declared: number | undefined,\n    fallback: number,\n    pluginName: string\n): number {\n    if (declared === undefined) return fallback;\n    if (!Number.isFinite(declared) || declared <= 0) {\n        throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [\n            pluginName,\n            `lifecycle ${field}.timeout must be a positive number of milliseconds`\n        ]);\n    }\n    return declared;\n}\n\n/** @internal */\nexport function resolveLifecycleSpec(\n    spec: PluginLifecycleSpec | undefined,\n    pluginName: string\n): ResolvedPluginLifecycleSpec {\n    return {\n        init: {\n            phase: spec?.init?.phase ?? StartupPhase.Configuration,\n            timeout: timeoutOf('init', spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)\n        },\n        ready: {\n            timeout: timeoutOf('ready', spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName)\n        },\n        dispose: {\n            phase: spec?.dispose?.phase ?? ShutdownPhase.Disconnect,\n            timeout: timeoutOf('dispose', spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)\n        }\n    };\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\nimport { Logger } from '@seedcord/logger';\n\nimport { getDevChannel } from '@hmr/devChannel';\n\nimport { resolveLifecycleSpec } from './lifecycle';\n\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type { TransportOf, PluginOptions, RuntimeOf } from './options';\nimport type { CoreBase } from '@interfaces/CoreBase';\nimport type { Tail, HmrAware, HmrUpdateEvent } from '@seedcord/types';\n\nexport interface Initializeable {\n    init(): Promise<void>;\n}\n\n/** @internal */\nconst resolvedSpecSlot = Symbol('seedcord.plugin.spec');\n\n/**\n * Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,\n * implements `init()`, and reads the framework surface through `this.core`.\n *\n * @typeParam Opts - The plugin's declared {@link PluginOptions}.\n * @typeParam TCore - The host type `this.core` resolves to. Each transport binds it to its own `Core`.\n */\nexport abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase>\n    implements Initializeable, HmrAware\n{\n    /** @internal phantom, never set at runtime */\n    declare readonly __transport?: TransportOf<Opts>;\n    /** @internal phantom, never set at runtime */\n    declare readonly __runtime?: RuntimeOf<Opts>;\n\n    /** @internal */\n    readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;\n\n    /** Logs under the plugin's class name, on the channel its attach key sets. */\n    public readonly logger: Logger;\n\n    // CoreBase here keeps the augmented Core out of ConstructorParameters, which attach reads\n    constructor(\n        private readonly host: CoreBase,\n        spec?: PluginLifecycleSpec\n    ) {\n        this.logger = new Logger(this.constructor.name);\n        this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);\n    }\n\n    /** The host, typed to the transport whose `Plugin` base this class extends. */\n    protected get core(): TCore {\n        // justified: each transport binds TCore to the Core its own host satisfies\n        return this.host as TCore;\n    }\n\n    abstract init(): Promise<void>;\n\n    /**\n     * Runs in the startup Ready phase, after `init()`. The gateway client is logged in by this phase,\n     * and the http host runs its server-bind and health tasks in the same phase.\n     */\n    ready?(): Promise<void>;\n\n    /** Runs during teardown, only when `init()` resolved. */\n    dispose?(): Promise<void>;\n\n    /**\n     * Throws a `SeedcordError` that contains the plugin class name and the reason.\n     *\n     * @param reason - Why the options are invalid.\n     */\n    protected rejectOptions(reason: string): never {\n        throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);\n    }\n\n    /** Override to reload plugin state on an HMR update. */\n    public onHmr(_event: HmrUpdateEvent): Promise<void> {\n        return Promise.resolve();\n    }\n\n    /**\n     * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.\n     * @param patterns - Glob patterns relative to the project root\n     */\n    protected registerCriticalFiles(patterns: string[]): void {\n        getDevChannel()?.send('seedcord:register-critical-files', { patterns });\n    }\n}\n\n/** @internal */\nexport function resolvedLifecycleSpecOf(plugin: PluginLike): ResolvedPluginLifecycleSpec {\n    return plugin[resolvedSpecSlot];\n}\n\nexport type { PluginLifecycleSpec } from './lifecycle';\nexport type { PluginOptions } from './options';\n\n// a bound of Plugin<{}> rejects every plugin that declares an option, since Plugin<A> and Plugin<B>\n// are mutually unassignable. every member here must stay Opts-independent.\n/** @internal */\nexport type PluginLike = Pick<Plugin, 'init' | 'ready' | 'dispose' | 'logger' | 'onHmr' | typeof resolvedSpecSlot>;\n\n// a `CoreBase` first parameter rejects a narrowing ctor on its own, and it also collapses\n// `InstanceType<Ctor>` to `PluginLike` at every attach call. CoreParamAssert checks it instead.\n/** @internal */\nexport type PluginCtor<TPlugin extends PluginLike = PluginLike> = new (...args: any[]) => TPlugin;\n\n/** @internal */\nexport type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;\n\ntype CoreParamTooNarrow = Record<\n    'this plugin constructor must take CoreBase as its first parameter and read the transport Core off this.core',\n    never\n>;\n\n// a narrowed first parameter fails `CoreBase extends Param`\n/** @internal */\nexport type CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0]\n    ? unknown\n    : CoreParamTooNarrow;\n"],"mappings":";;;;;;;AAsBA,MAAM,0BAA0B;AAChC,MAAM,2BAA2B;AACjC,MAAM,6BAA6B;AAEnC,SAAS,UACL,OACA,UACA,UACA,YACM;CACN,IAAI,aAAa,QAAW,OAAO;CACnC,IAAI,CAAC,OAAO,SAAS,QAAQ,KAAK,YAAY,GAC1C,MAAM,IAAIA,wCAAcC,mCAAkB,uBAAuB,CAC7D,YACA,aAAa,MAAM,mDACvB,CAAC;CAEL,OAAO;AACX;;AAGA,SAAgB,qBACZ,MACA,YAC2B;CAC3B,OAAO;EACH,MAAM;GACF,OAAO,MAAM,MAAM;GACnB,SAAS,UAAU,QAAQ,MAAM,MAAM,SAAS,yBAAyB,UAAU;EACvF;EACA,OAAO,EACH,SAAS,UAAU,SAAS,MAAM,OAAO,SAAS,0BAA0B,UAAU,EAC1F;EACA,SAAS;GACL,OAAO,MAAM,SAAS;GACtB,SAAS,UAAU,WAAW,MAAM,SAAS,SAAS,4BAA4B,UAAU;EAChG;CACJ;AACJ;;;;;AC1CA,MAAM,mBAAmB,OAAO,sBAAsB;;;;;;;;AAStD,IAAsB,SAAtB,MAEA;CAcyB;;CAPrB,CAAU;;CAGV,AAAgB;CAGhB,YACI,AAAiB,MACjB,MACF;EAFmB;EAGjB,KAAK,SAAS,IAAIC,wBAAO,KAAK,YAAY,IAAI;EAC9C,KAAK,oBAAoB,qBAAqB,MAAM,KAAK,YAAY,IAAI;CAC7E;;CAGA,IAAc,OAAc;EAExB,OAAO,KAAK;CAChB;;;;;;CAkBA,AAAU,cAAc,QAAuB;EAC3C,MAAM,IAAIC,wCAAcC,mCAAkB,uBAAuB,CAAC,KAAK,YAAY,MAAM,MAAM,CAAC;CACpG;;CAGA,AAAO,MAAM,QAAuC;EAChD,OAAO,QAAQ,QAAQ;CAC3B;;;;;CAMA,AAAU,sBAAsB,UAA0B;EACtD,iCAAc,CAAC,EAAE,KAAK,oCAAoC,EAAE,SAAS,CAAC;CAC1E;AACJ;;AAGA,SAAgB,wBAAwB,QAAiD;CACrF,OAAO,OAAO;AAClB"}