glassframe-protocol 1.2.0

package/dist/src/layers/AntiNukeLayer.js

@@ -0,0 +1,278 @@
+"use strict";
+
+const { AuditLogEvent, PermissionsBitField } = require("discord.js");
+const Layer = require("../core/Layer");
+const ProtocolCache = require("../core/Cache");
+
+const EVENT_MAP = {
+  [AuditLogEvent.ChannelDelete]: "channelDelete",
+  [AuditLogEvent.ChannelCreate]: "channelCreate",
+  [AuditLogEvent.RoleDelete]: "roleDelete",
+  [AuditLogEvent.RoleCreate]: "roleCreate",
+  [AuditLogEvent.MemberBanAdd]: "memberBanAdd",
+  [AuditLogEvent.MemberKick]: "memberKick",
+  [AuditLogEvent.WebhookCreate]: "webhookCreate",
+  [AuditLogEvent.BotAdd]: "botAdd",
+  [AuditLogEvent.GuildUpdate]: "guildUpdate",
+  [AuditLogEvent.RoleUpdate]: "roleUpdate",
+  [AuditLogEvent.InviteCreate]: "inviteCreate",
+  [AuditLogEvent.EmojiCreate]: "emojiCreate",
+  [AuditLogEvent.EmojiDelete]: "emojiDelete",
+  [AuditLogEvent.StickerCreate]: "stickerCreate",
+  [AuditLogEvent.StickerDelete]: "stickerDelete"
+};
+
+class AntiNukeLayer extends Layer {
+  constructor(frame) {
+    super("antiNuke", frame);
+    this.actionLog = new Map(); // guildId -> executorId -> { type: timestamps[] }
+    this.snapshots = new ProtocolCache("nuke-snapshots", { ttlMs: 0 });
+    // webhookId -> { executorId, guildId } for webhooks created recently
+    // enough to still be worth watching for a message-flood pattern.
+    this.recentWebhooks = new ProtocolCache("recent-webhooks", { ttlMs: 0 });
+    this.webhookMessageCounts = new Map(); // webhookId -> timestamps[]
+  }
+
+  onEnable() {
+    this._listen(this.client, "guildAuditLogEntryCreate", (entry, guild) =>
+      this._handleEntry(entry, guild).catch(() => {})
+    );
+    if (this.config.webhookAbuse.enabled) {
+      this._listen(this.client, "messageCreate", (message) => this._handleWebhookMessage(message).catch(() => {}));
+    }
+    // Give every guild an immediate role audit the moment AntiNuke is armed.
+    for (const guild of this.client.guilds.cache.values()) {
+      this._auditRoles(guild).catch(() => {});
+    }
+  }
+
+  onDisable() {
+    this.actionLog.clear();
+    this.webhookMessageCounts.clear();
+  }
+
+  _record(guildId, executorId, type) {
+    const now = Date.now();
+    if (!this.actionLog.has(guildId)) this.actionLog.set(guildId, new Map());
+    const guildMap = this.actionLog.get(guildId);
+    if (!guildMap.has(executorId)) guildMap.set(executorId, {});
+    const byType = guildMap.get(executorId);
+    const list = (byType[type] || []).filter((t) => now - t < this.config.windowMs);
+    list.push(now);
+    byType[type] = list;
+    return list.length;
+  }
+
+  async _handleEntry(entry, guild) {
+    const type = EVENT_MAP[entry.action];
+    if (!type) return;
+    this.frame.performance.recordEvent(`antiNuke.auditEntry.${type}`);
+
+    const executor = entry.executor;
+    if (!executor || executor.id === this.client.user.id) return;
+    if (executor.id === guild.ownerId) return;
+    if (this.frame.whitelist.has(executor.id)) return;
+
+    if (type === "roleUpdate" && this.config.watchDangerousGrants) {
+      await this._checkDangerousGrant(entry, guild, executor);
+    }
+    if (type === "guildUpdate" && this.config.watchVanityChanges) {
+      await this._checkVanityChange(entry, guild, executor);
+    }
+    if (type === "inviteCreate" && this.config.watchInviteAbuse) {
+      await this._checkInviteAbuse(entry, guild, executor);
+    }
+    if (type === "webhookCreate" && this.config.webhookAbuse.enabled) {
+      this.recentWebhooks.set(
+        entry.targetId,
+        { executorId: executor.id, guildId: guild.id },
+        this.config.webhookAbuse.watchPeriodMs
+      );
+    }
+
+    // Invite creation doesn't count toward the generic burst threshold below -
+    // a legitimate server creates invites routinely, so it's special-cased
+    // above (and only escalated for non-staff + unrestricted configs)
+    // instead of contributing to a raw count.
+    if (type === "inviteCreate") return;
+
+    const count = this._record(guild.id, executor.id, type);
+    const threshold = this.config.thresholds[type];
+    if (!threshold || count < threshold) return;
+
+    this.snapshot(guild); // forensic context captured at the moment of the incident
+
+    let member = null;
+    try {
+      member = await guild.members.fetch(executor.id);
+    } catch {
+      /* executor already left the server */
+    }
+    if (!member) return;
+
+    await this.frame.punishmentEngine.report({
+      guild,
+      member,
+      layer: "antiNuke",
+      weight: 60,
+      reason: `${count}x ${type} inside ${this.config.windowMs / 1000}s`
+    });
+  }
+
+  /** A role gaining Administrator/ManageGuild/etc is worth flagging the moment it happens. */
+  async _checkDangerousGrant(entry, guild, executor) {
+    const dangerous = this.frame.config.roleAnalysis.dangerousPermissions;
+    const change = entry.changes?.find((c) => c.key === "permissions");
+    if (!change) return;
+
+    const newPerms = new PermissionsBitField(BigInt(change.new ?? 0));
+    const oldPerms = new PermissionsBitField(BigInt(change.old ?? 0));
+    const gained = dangerous.filter(
+      (p) => newPerms.has(PermissionsBitField.Flags[p]) && !oldPerms.has(PermissionsBitField.Flags[p])
+    );
+    if (!gained.length) return;
+
+    const role = guild.roles.cache.get(entry.targetId);
+
+    await this.frame.logger.log(guild, {
+      level: "alert",
+      title: "Dangerous Permission Grant Detected",
+      description: `${executor.tag} granted **${gained.join(", ")}** to role ${role ? role.name : entry.targetId}.`,
+      fields: [
+        { name: "Auto-revert", value: this.config.autoRevertDangerousGrants ? "enabled" : "disabled - review manually" }
+      ],
+      dedupeKey: `antinuke:grant:${entry.targetId}`
+    });
+
+    if (this.config.autoRevertDangerousGrants && role) {
+      try {
+        await role.setPermissions(oldPerms, "GlassFrame Protocol: reverting unauthorized dangerous permission grant");
+      } catch (err) {
+        this.frame.emit("warning", { layer: "antiNuke", message: `auto-revert failed: ${err.message}` });
+      }
+    }
+  }
+
+  async _checkVanityChange(entry, guild, executor) {
+    const watched = new Set(["name", "icon", "vanityURLCode"]);
+    const changed = (entry.changes || []).filter((c) => watched.has(c.key));
+    if (!changed.length) return;
+
+    await this.frame.logger.log(guild, {
+      level: "warn",
+      title: "Server Identity Changed",
+      description: `${executor.tag} changed: ${changed.map((c) => c.key).join(", ")}.`,
+      dedupeKey: `antinuke:identity:${executor.id}`
+    });
+  }
+
+  /**
+   * An unrestricted invite (no expiry, no use limit) is routine when a real
+   * staff member sets up the server's permanent "join us" link - flagging
+   * every one of those would just be noise. It's only worth a look when
+   * whoever created it isn't recognized as trusted staff.
+   */
+  async _checkInviteAbuse(entry, guild, executor) {
+    const changes = entry.changes || [];
+    const maxAge = changes.find((c) => c.key === "max_age");
+    const maxUses = changes.find((c) => c.key === "max_uses");
+    const isUnlimitedAge = !maxAge || Number(maxAge.new) === 0;
+    const isUnlimitedUses = !maxUses || Number(maxUses.new) === 0;
+    if (!isUnlimitedAge || !isUnlimitedUses) return;
+
+    let member = null;
+    try {
+      member = await guild.members.fetch(executor.id);
+    } catch {
+      /* left already */
+    }
+    const trust = member ? this.frame.roleAnalyzer.trustLevel(member) : "LOW";
+    if (trust === "HIGH" || trust === "PROTECTED") return;
+
+    await this.frame.logger.log(guild, {
+      level: "warn",
+      title: "Unrestricted Invite Created By Non-Staff Member",
+      description: `${executor.tag} (trust: ${trust}) created an invite with no expiry and no use limit.`,
+      dedupeKey: `antinuke:invite:${executor.id}`
+    });
+  }
+
+  /**
+   * Webhook messages never carry a guild member, so BasicSecurityLayer's
+   * per-author spam buffer can't see them - a "create webhook, then flood
+   * messages through it" nuke would otherwise slip past every other layer.
+   * This traces a flood back to whoever created the webhook (recorded in
+   * `recentWebhooks` above) and contains it by deleting the webhook itself.
+   */
+  async _handleWebhookMessage(message) {
+    if (!message.webhookId || !message.guild) return;
+    const info = this.recentWebhooks.get(message.webhookId);
+    if (!info) return;
+
+    const cfg = this.config.webhookAbuse;
+    const now = Date.now();
+    const list = (this.webhookMessageCounts.get(message.webhookId) || []).filter((t) => now - t < cfg.windowMs);
+    list.push(now);
+    this.webhookMessageCounts.set(message.webhookId, list);
+    if (list.length < cfg.messageThreshold) return;
+
+    this.webhookMessageCounts.delete(message.webhookId); // one alert per burst, not one per message past threshold
+    const guild = message.guild;
+
+    try {
+      const webhooks = await guild.fetchWebhooks();
+      const hook = webhooks.get(message.webhookId);
+      if (hook) await hook.delete("GlassFrame Protocol: webhook message-flood containment");
+    } catch (err) {
+      this.frame.emit("warning", { layer: "antiNuke", message: `failed to delete abusive webhook: ${err.message}` });
+    }
+
+    await this.frame.logger.log(guild, {
+      level: "alert",
+      title: "Webhook Message Flood - Webhook Removed",
+      description: `A recently created webhook sent ${list.length}+ messages inside ${cfg.windowMs / 1000}s and has been deleted.`,
+      dedupeKey: `antinuke:webhook-flood:${message.webhookId}`
+    });
+
+    let member = null;
+    try {
+      member = await guild.members.fetch(info.executorId);
+    } catch {
+      /* executor already left */
+    }
+    if (member) {
+      await this.frame.punishmentEngine.report({
+        guild,
+        member,
+        layer: "antiNuke",
+        weight: 70,
+        reason: `created a webhook that then flooded ${list.length}+ messages inside ${cfg.windowMs / 1000}s`
+      });
+    }
+  }
+
+  /** Cheap forensic snapshot kept only in memory, purely as context for future alerts. */
+  snapshot(guild) {
+    const data = {
+      takenAt: Date.now(),
+      roles: guild.roles.cache.map((r) => ({ id: r.id, name: r.name, position: r.position })),
+      channels: guild.channels.cache.map((c) => ({ id: c.id, name: c.name, type: c.type }))
+    };
+    this.snapshots.set(guild.id, data, this.config.snapshotTtlMs);
+    return data;
+  }
+
+  async _auditRoles(guild) {
+    const flags = this.frame.roleAnalyzer.scanRoles(guild);
+    if (!flags.length) return;
+
+    await this.frame.logger.log(guild, {
+      level: "warn",
+      title: "Role Audit - Possible Impersonation/Permission Mismatch",
+      description: flags.map((f) => `**${f.name}** (${f.roleId}) - ${f.reason}`).join("\n"),
+      dedupeKey: "antinuke:role-audit"
+    });
+  }
+}
+
+module.exports = AntiNukeLayer;

package/dist/src/layers/AntiRaidLayer.js

@@ -0,0 +1,144 @@
+"use strict";
+
+const Layer = require("../core/Layer");
+const { suspiciousUsernameEntropy } = require("../utils/nlpEngine");
+
+class AntiRaidLayer extends Layer {
+  constructor(frame) {
+    super("antiRaid", frame);
+    this.joinTimestamps = new Map(); // guildId -> timestamps[]
+    this.lockedDown = new Map(); // guildId -> unlock timestamp
+    this.previousVerification = new Map(); // guildId -> original verification level
+    this.joinProfiles = new Map(); // guildId -> [{ at, created }] for cluster correlation
+  }
+
+  onEnable() {
+    this._listen(this.client, "guildMemberAdd", (member) => this._handleJoin(member).catch(() => {}));
+  }
+
+  onDisable() {
+    this.joinTimestamps.clear();
+    this.joinProfiles.clear();
+  }
+
+  isLockedDown(guildId) {
+    const until = this.lockedDown.get(guildId);
+    return typeof until === "number" && Date.now() < until;
+  }
+
+  _recordJoin(guildId) {
+    const now = Date.now();
+    const cfg = this.config;
+    const list = (this.joinTimestamps.get(guildId) || []).filter((t) => now - t < cfg.joinWindowMs);
+    list.push(now);
+    this.joinTimestamps.set(guildId, list);
+    return list.length;
+  }
+
+  /** 0-100 composite: newer account + suspicious entropy + no avatar all stack. */
+  _altScore(user) {
+    const cfg = this.config;
+    let score = 0;
+    const age = Date.now() - user.createdTimestamp;
+    if (age < cfg.minAccountAgeMs) score += 40 * (1 - age / cfg.minAccountAgeMs);
+
+    const entropyCheck = suspiciousUsernameEntropy(user.username, cfg.usernameEntropyFloor, cfg.usernameEntropyCeiling);
+    if (entropyCheck.suspicious) score += 35;
+    if (!user.avatar) score += 15;
+
+    return { score: Math.round(score), entropyCheck };
+  }
+
+  /**
+   * Evasion-resistant raid signal: a bulk-registered account farm often
+   * trickles members in slowly enough that the raw join-rate counter above
+   * never trips, but the accounts themselves were still all created within
+   * the same narrow window months (or minutes) ago. Catching that pattern
+   * doesn't require a fast join rate at all - just enough joiners, over a
+   * longer window, who share a suspiciously similar creation time.
+   */
+  _clusterScore(guildId, user) {
+    const cfg = this.config.cluster;
+    const now = Date.now();
+    const list = (this.joinProfiles.get(guildId) || []).filter((p) => now - p.at < cfg.windowMs);
+    list.push({ at: now, created: user.createdTimestamp });
+    this.joinProfiles.set(guildId, list);
+
+    if (list.length < cfg.minClusterSize) return { flagged: false, clusterSize: 0 };
+
+    const closeCreations = list.filter((p) => Math.abs(p.created - user.createdTimestamp) < cfg.creationToleranceMs);
+    if (closeCreations.length >= cfg.minClusterSize) {
+      return { flagged: true, clusterSize: closeCreations.length };
+    }
+    return { flagged: false, clusterSize: closeCreations.length };
+  }
+
+  async _handleJoin(member) {
+    const { guild, user } = member;
+    this.frame.performance.recordEvent("antiRaid.guildMemberAdd");
+    const joinCount = this._recordJoin(guild.id);
+    const { score: altScore, entropyCheck } = this._altScore(user);
+    const cluster = this._clusterScore(guild.id, user);
+
+    const reasons = [];
+    if (altScore >= this.config.altScoreThreshold) reasons.push(`alt-account score ${altScore}/100`);
+    if (entropyCheck.suspicious) reasons.push(`username pattern: ${entropyCheck.reason}`);
+    if (cluster.flagged) reasons.push(`part of a ${cluster.clusterSize}-account creation-time cluster`);
+    if (this.isLockedDown(guild.id)) reasons.push("joined during active raid lockdown");
+
+    if ((this.isLockedDown(guild.id) || cluster.flagged) && reasons.length) {
+      const weight = reasons.length * 25;
+      await this.frame.punishmentEngine.report({ guild, member, layer: "antiRaid", weight, reason: reasons.join("; ") });
+    }
+
+    if (joinCount >= this.config.joinThreshold && !this.isLockedDown(guild.id)) {
+      await this._triggerLockdown(guild, joinCount);
+    }
+  }
+
+  async _triggerLockdown(guild, joinCount) {
+    const unlockAt = Date.now() + this.config.lockdownDurationMs;
+    this.lockedDown.set(guild.id, unlockAt);
+
+    try {
+      if (!this.previousVerification.has(guild.id)) {
+        this.previousVerification.set(guild.id, guild.verificationLevel);
+      }
+      await guild.setVerificationLevel(4, "GlassFrame Protocol: anti-raid lockdown");
+    } catch (err) {
+      this.frame.emit("warning", { layer: "antiRaid", message: `failed to raise verification level: ${err.message}` });
+    }
+
+    await this.frame.logger.log(guild, {
+      level: "alert",
+      title: "Raid Detected - Lockdown Engaged",
+      description: `${joinCount} joins inside ${this.config.joinWindowMs / 1000}s. Verification level temporarily raised.`,
+      fields: [{ name: "Duration", value: `${this.config.lockdownDurationMs / 60000} min` }],
+      dedupeKey: "antiraid:lockdown"
+    });
+
+    const timer = setTimeout(() => this._endLockdown(guild), this.config.lockdownDurationMs);
+    timer.unref?.();
+  }
+
+  async _endLockdown(guild) {
+    this.lockedDown.delete(guild.id);
+    const original = this.previousVerification.get(guild.id);
+    try {
+      if (original !== undefined) await guild.setVerificationLevel(original, "GlassFrame Protocol: lockdown ended");
+    } catch (err) {
+      this.frame.emit("warning", { layer: "antiRaid", message: `failed to restore verification level: ${err.message}` });
+    } finally {
+      this.previousVerification.delete(guild.id);
+    }
+
+    await this.frame.logger.log(guild, {
+      level: "ok",
+      title: "Lockdown Lifted",
+      description: "Join activity normalized. Verification level restored.",
+      dedupeKey: "antiraid:lockdown-end"
+    });
+  }
+}
+
+module.exports = AntiRaidLayer;

package/dist/src/layers/BasicSecurityLayer.js

@@ -0,0 +1,111 @@
+"use strict";
+
+const Layer = require("../core/Layer");
+const { classifyMessage } = require("../utils/nlpEngine");
+
+class BasicSecurityLayer extends Layer {
+  constructor(frame) {
+    super("basicSecurity", frame);
+    this.buffers = new Map(); // userId -> { timestamps, lastContent, dupCount }
+  }
+
+  onEnable() {
+    this._listen(this.client, "messageCreate", (message) => this._handle(message).catch(() => {}));
+  }
+
+  onDisable() {
+    this.buffers.clear();
+  }
+
+  _bufferFor(userId) {
+    if (!this.buffers.has(userId)) {
+      this.buffers.set(userId, { timestamps: [], lastContent: "", dupCount: 0 });
+    }
+    return this.buffers.get(userId);
+  }
+
+  async _handle(message) {
+    if (!message.guild || message.author.bot) return;
+    const done = this.frame.performance.time("basicSecurity.messageCreate");
+    this.frame.performance.recordEvent("basicSecurity.messageCreate");
+
+    const cfg = this.config;
+    const buf = this._bufferFor(message.author.id);
+    const now = Date.now();
+
+    buf.timestamps = buf.timestamps.filter((t) => now - t < cfg.spam.windowMs);
+    buf.timestamps.push(now);
+
+    if (message.content && message.content === buf.lastContent) buf.dupCount++;
+    else {
+      buf.dupCount = 1;
+      buf.lastContent = message.content;
+    }
+
+    const mentionCount = message.mentions.users.size + message.mentions.roles.size;
+    const classification = classifyMessage(message.content || "");
+    const linkFlag = this._checkLinks(message.content || "");
+
+    const reasons = [];
+    let weight = 0;
+
+    if (buf.timestamps.length >= cfg.spam.messageThreshold) {
+      reasons.push(`message rate ${buf.timestamps.length}/${cfg.spam.windowMs / 1000}s`);
+      weight += 20;
+    }
+    if (buf.dupCount >= cfg.spam.duplicateThreshold) {
+      reasons.push(`duplicate flood x${buf.dupCount}`);
+      weight += 20;
+    }
+    if (mentionCount >= cfg.mentionSpam.maxMentionsPerMessage) {
+      reasons.push(`mention spam (${mentionCount})`);
+      weight += 25;
+    }
+    if (classification.scam >= cfg.nlp.scamScoreThreshold) {
+      reasons.push(`scam language (${classification.scam.toFixed(2)})`);
+      weight += 35;
+    }
+    if (classification.phishing >= cfg.nlp.phishingScoreThreshold) {
+      reasons.push(`phishing language (${classification.phishing.toFixed(2)})`);
+      weight += 35;
+    }
+    if (linkFlag) {
+      reasons.push(linkFlag);
+      weight += 30;
+    }
+
+    if (!reasons.length) {
+      done();
+      return;
+    }
+
+    try {
+      if (message.deletable) await message.delete();
+    } catch {
+      /* best effort - still report the signal even if delete fails */
+    }
+
+    await this.frame.punishmentEngine.report({
+      guild: message.guild,
+      member: message.member,
+      layer: "basicSecurity",
+      weight,
+      reason: reasons.join("; ")
+    });
+    done();
+  }
+
+  /** Delegates to the shared PhishingDatabase (server blocklist + fast heuristics). */
+  _checkLinks(text) {
+    const urls = text.match(/https?:\/\/[^\s]+/gi);
+    if (!urls) return null;
+
+    for (const url of urls) {
+      const reason = this.frame.phishingDatabase.check(url);
+      if (reason) return reason;
+    }
+    return null;
+  }
+}
+
+module.exports = BasicSecurityLayer;

package/dist/src/logging/ComponentsV2.js

@@ -0,0 +1,44 @@
+"use strict";
+
+const {
+  ContainerBuilder,
+  TextDisplayBuilder,
+  SeparatorBuilder,
+  SeparatorSpacingSize,
+  MessageFlags
+} = require("discord.js");
+
+const COLORS = { info: 0x5865f2, warn: 0xf2a65a, alert: 0xed4245, ok: 0x57f287 };
+
+/**
+ * Builds a Components V2 payload (no legacy EmbedBuilder anywhere in this
+ * library). Pass the return value directly to channel.send() / interaction
+ * .reply()/.update(). `count` renders a "(xN)" badge next to the title when
+ * SmartLogger has merged repeated events together.
+ */
+function buildLogMessage({ level = "info", title, description, fields = [], footer, count }) {
+  const container = new ContainerBuilder().setAccentColor(COLORS[level] ?? COLORS.info);
+
+  const heading = count && count > 1 ? `**${title}** (x${count})` : `**${title}**`;
+  container.addTextDisplayComponents(new TextDisplayBuilder().setContent(heading));
+
+  if (description) {
+    container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+    container.addTextDisplayComponents(new TextDisplayBuilder().setContent(description));
+  }
+
+  if (fields.length) {
+    container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+    const fieldText = fields.map((f) => `**${f.name}**\n${f.value}`).join("\n\n");
+    container.addTextDisplayComponents(new TextDisplayBuilder().setContent(fieldText));
+  }
+
+  container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+  container.addTextDisplayComponents(
+    new TextDisplayBuilder().setContent(`-# GlassFrame Protocol${footer ? " - " + footer : ""}`)
+  );
+
+  return { flags: MessageFlags.IsComponentsV2, components: [container] };
+}
+
+module.exports = { buildLogMessage, COLORS };

package/dist/src/logging/SmartLogger.js

@@ -0,0 +1,84 @@
+"use strict";
+
+const { buildLogMessage } = require("./ComponentsV2");
+
+/**
+ * Every GlassFrame alert goes through one gate that:
+ *  (a) merges near-duplicate events inside a short window into a single,
+ *      updated message instead of one message per event, and
+ *  (b) never sends to a guild's log channel faster than a configured floor,
+ * so a burst never turns into a wall of messages or a Discord 429.
+ */
+class SmartLogger {
+  constructor(getLogChannel, config, { debug = false } = {}) {
+    this.getLogChannel = getLogChannel;
+    this.config = config.logging;
+    this.debug = debug;
+    this.pending = new Map(); // dedupeKey -> { count, payload, sent }
+    this.lastSend = new Map(); // guildId -> timestamp
+  }
+
+  async log(guild, payload) {
+    const key = payload.dedupeKey ? `${guild.id}:${payload.dedupeKey}` : null;
+
+    if (key && this.pending.has(key)) {
+      const entry = this.pending.get(key);
+      entry.count += 1;
+      entry.payload = payload;
+      this._debug(`merge ${key} -> x${entry.count}`);
+      return entry.sent;
+    }
+
+    const entry = { count: 1, payload, sent: null };
+    if (key) this.pending.set(key, entry);
+
+    entry.sent = await this._deliver(guild, payload, key ? 1 : undefined);
+
+    if (key) {
+      const timer = setTimeout(async () => {
+        const final = this.pending.get(key);
+        this.pending.delete(key);
+        if (final && final.count > 1 && final.sent) {
+          try {
+            const updated = buildLogMessage({ ...final.payload, count: final.count });
+            await final.sent.edit(updated);
+            this._debug(`final edit ${key} -> x${final.count}`);
+          } catch (err) {
+            this._debug(`edit failed for ${key}: ${err.message}`);
+          }
+        }
+      }, this.config.aggregationWindowMs);
+      timer.unref?.();
+    }
+
+    return entry.sent;
+  }
+
+  async _deliver(guild, payload, count) {
+    await this._respectRateFloor(guild.id);
+    const channel = await this.getLogChannel(guild);
+    if (!channel) return null;
+
+    const message = buildLogMessage({ ...payload, count });
+    try {
+      const sent = await channel.send(message);
+      this.lastSend.set(guild.id, Date.now());
+      return sent;
+    } catch (err) {
+      console.error("[GlassFrame:SmartLogger] failed to send log:", err.message);
+      return null;
+    }
+  }
+
+  async _respectRateFloor(guildId) {
+    const last = this.lastSend.get(guildId) || 0;
+    const wait = this.config.minSendIntervalMs - (Date.now() - last);
+    if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+  }
+
+  _debug(msg) {
+    if (this.debug) console.log(`[GlassFrame:SmartLogger] ${msg}`);
+  }
+}
+
+module.exports = SmartLogger;