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

package/dist/Plugin-3rlH0uxH.d.mts

@@ -0,0 +1,620 @@
+import { FrameworkChannel, Logger } from "@seedcord/logger";
+import { TypedEventEmitter } from "@seedcord/event-emitter";
+import { Config, EventFrequency, HmrAware, HmrUpdateEvent, IRateLimiter, RenderContext, ReplyResponse, Store, 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;
+  /** 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/plugin/options.d.ts
+/** A capability a plugin declares through `needs`, each surfacing a typed `ctx` field. */
+type PluginNeed = 'client' | 'token' | 'rest';
+/**
+ * The options a plugin declares as its `Plugin<Opts>` type argument. Authors write unions for `needs`,
+ * e.g. `needs: 'token' | 'rest'`.
+ */
+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';
+  /** Capabilities the plugin requests, each a typed `ctx` field. */
+  needs?: PluginNeed;
+}
+/** @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 */
+type NeedsOf<Opts extends PluginOptions> = undefined extends Opts['needs'] ? never : NonNullable<Opts['needs']>;
+/** @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/context.d.ts
+/**
+ * The type each `ctx` capability resolves to. Empty in core, each transport augments it through
+ * declaration merging.
+ *
+ * @example
+ * ```typescript
+ * declare module '@seedcord/core' {
+ *   interface PluginCapabilityTypes {
+ *     client: Client;
+ *     rest: REST;
+ *   }
+ * }
+ * ```
+ */
+interface PluginCapabilityTypes {}
+type CapabilityType<Key extends PluginNeed, Fallback> = Key extends keyof PluginCapabilityTypes ? PluginCapabilityTypes[Key] : Fallback;
+type CapabilityValue<TNeeds extends PluginNeed, Key extends PluginNeed, Value> = Key extends TNeeds ? Value : never;
+/**
+ * The framework surface a plugin reads through `this.ctx`, typed by its declared `needs`.
+ *
+ * Always available: `config` and `store`. Each capability resolves to its value only when
+ * the plugin declared that key, otherwise `never`. The logger comes from `this.logger`.
+ *
+ * @typeParam TNeeds - The plugin's declared `needs` union.
+ */
+interface PluginContext<TNeeds extends PluginNeed = never> {
+  readonly config: Config;
+  readonly store: Store<'charge'>;
+  readonly client: CapabilityValue<TNeeds, 'client', CapabilityType<'client', unknown>>;
+  readonly token: CapabilityValue<TNeeds, 'token', string>;
+  /**
+   * The REST client. On http, the client has no token until the Ready phase, so a call from
+   * `init()` sends without a token and returns a 401.
+   */
+  readonly rest: CapabilityValue<TNeeds, 'rest', CapabilityType<'rest', unknown>>;
+}
+/** @internal */
+type StoredPluginContext = Pick<PluginContext, 'config' | 'store'> & {
+  client?: unknown;
+  token?: string | undefined;
+  rest?: unknown;
+};
+/**
+ * The capability arms a transport supplies from its own Bot/client. `attach` merges them into each
+ * plugin's ctx.
+ *
+ * @internal
+ */
+interface PluginCapabilities {
+  readonly client?: unknown;
+  readonly token?: string | undefined;
+  readonly rest?: unknown;
+}
+/** @internal unset until attach installs the built ctx */
+declare const pluginContextSlot: unique symbol;
+//#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. Empty on http. */
+  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/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.ctx`.
+ *
+ * @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;
+  /** @internal */
+  [pluginContextSlot]?: StoredPluginContext;
+  /** Logs under the plugin's class name, on the channel its attach key names. */
+  readonly logger: Logger;
+  constructor(host: CoreBase, spec?: PluginLifecycleSpec);
+  /** The host, typed to the transport whose `Plugin` base this class extends. */
+  protected get core(): TCore;
+  /** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */
+  protected get ctx(): PluginContext<NeedsOf<Opts>>;
+  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>;
+  /**
+   * Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the
+   * plugin class 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 | typeof pluginContextSlot>;
+/** @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 { Notice as A, EventMetadataKey as B, Subscriber as C, SubscriptionData as D, FaultSource as E, checkAckLegality as F, MiddlewareMetadataKey as G, InteractionMetadataKey as H, sendTarget as I, SubscribeMetadataKey as K, AckTrace as L, reportedWrite as M, AckState as N, SubscriptionKey as O, ReplyMethod as P, PublishDefault as R, SubscriberRegistration as S, DispatchOutcome as T, InteractionRouteKeys as U, GatedMetadataKey as V, InteractionRoutes as W, Transport as _, PluginCtor as a, Bus as b, ShutdownPhase as c, PluginCapabilityTypes as d, PluginContext as f, RuntimeAssert as g, Runtime as h, PluginArgs as i, ReplyTelemetry as j, Subscriptions as k, StartupPhase as l, PluginOptions as m, Initializeable as n, PluginLike as o, ChannelKeyAssert as p, WebhookUrlMetadataKey as q, Plugin as r, PluginLifecycleSpec as s, CoreParamAssert as t, PluginCapabilities as u, TransportAssert as v, DefaultSubscriptions as w, StoredSubscriberCtor as x, CoreBase as y, CommandMetadataKey as z };
+//# sourceMappingURL=Plugin-3rlH0uxH.d.mts.map

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

@@ -2,6 +2,7 @@ const require_phases = require('./phases-C_BGNyVo.cjs');
 const require_devChannel = require('./devChannel-CoCmAVDx.cjs');
 let _seedcord_errors = require("@seedcord/errors");
 let _seedcord_errors_internal = require("@seedcord/errors/internal");
+let _seedcord_logger = require("@seedcord/logger");
 
 //#region src/plugin/context.ts
 /** @internal unset until attach installs the built ctx */
@@ -51,17 +52,25 @@ const resolvedSpecSlot = Symbol("seedcord.plugin.spec");
 * implements `init()`, and reads the framework surface through `this.ctx`.
 *
 * @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 names. */
+	logger;
+	constructor(host, spec) {
+		this.host = host;
+		this.logger = new _seedcord_logger.Logger(this.constructor.name);
 		this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);
 	}
+	/** The host, typed to the transport whose `Plugin` base this class extends. */
+	get core() {
+		return this.host;
+	}
 	/** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */
 	get ctx() {
 		return readPluginContext(this);
@@ -111,4 +120,4 @@ Object.defineProperty(exports, 'resolvedLifecycleSpecOf', {
     return resolvedLifecycleSpecOf;
   }
 });
-//# sourceMappingURL=Plugin-C2-VHrsX.cjs.map
+//# sourceMappingURL=Plugin-Cgp1a0uQ.cjs.map