@fraqjs/fraq 0.9.0 → 0.9.2

package/dist/index.d.mts

@@ -5514,20 +5514,36 @@ interface Command<P extends Pattern> {
   name: string;
   pattern: P;
   execute: Executor<P>;
+  description?: string;
+  aliases?: string[];
+  hidden?: boolean;
 }
 interface RawPattern<P extends Pattern> {
   pattern: P;
   execute: Executor<P>;
 }
+interface SessionReplyOptions {
+  withQuote?: boolean;
+  withMention?: boolean;
+}
 interface Session {
   raw: IncomingMessage;
-  reply(segments: OutgoingSegment_ZodInput[]): Promise<void>;
+  reply(
+    segments: OutgoingSegment_ZodInput[],
+    options?: SessionReplyOptions,
+  ): Promise<{
+    messageSeq: number;
+  }>;
+  reaction(type: 'face' | 'emoji', reactionId: string): Promise<void>;
 }
 declare class CommandBuilder<P extends Pattern = {}, S = Command<P>> {
   readonly name: string;
   private readonly sink;
   private readonly pattern;
   private executor?;
+  private description?;
+  private aliases?;
+  private hidden?;
   constructor(name: string, sink?: (command: Command<P>) => S);
   arg<K extends string, T>(
     key: K,
@@ -5540,6 +5556,9 @@ declare class CommandBuilder<P extends Pattern = {}, S = Command<P>> {
         ? RawPattern<P & { [K2 in K]: Parameter<T> }>
         : S
   >;
+  describe(description: string): CommandBuilder<P, S>;
+  alias(...aliases: string[]): CommandBuilder<P, S>;
+  hide(): CommandBuilder<P, S>;
   execute(executor: Executor<P>): S;
 }
 //#endregion
@@ -5598,6 +5617,7 @@ declare class Router {
   group(name: string): Router;
   filter(predicate: SessionPredicate): Router;
   routes(): RouteEntry[];
+  aliasesOf(name: string): string[];
   branches(session: Session): RouteBranch[];
   match(session: Session, message: IncomingMessage): RouteMatchResult | undefined;
   dispatch(session: Session, message: IncomingMessage): Promise<boolean>;
@@ -5607,6 +5627,7 @@ declare class Router {
   private matchGroup;
   private matchRawPattern;
   private branchesFrom;
+  private resolveAliasConflicts;
   private validatePattern;
   private capturePattern;
 }
@@ -5835,6 +5856,7 @@ export {
   ServiceClass,
   Session,
   SessionPredicate,
+  SessionReplyOptions,
   TypeInstruction,
   combineLogHandlers,
   createMilkyClient,

package/dist/index.mjs

@@ -64,12 +64,147 @@ function createMilkyClient(...params) {
 	} });
 }
 //#endregion
+//#region src/protocol/segment.ts
+function msg(strings, ...values) {
+	let buffer = "";
+	const segments = [];
+	for (let i = 0; i < strings.length; i++) {
+		buffer += strings[i];
+		if (i < values.length) {
+			const value = values[i];
+			if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") buffer += value.toString();
+			else {
+				if (buffer) {
+					segments.push({
+						type: "text",
+						data: { text: buffer }
+					});
+					buffer = "";
+				}
+				segments.push(value);
+			}
+		}
+	}
+	if (buffer) segments.push({
+		type: "text",
+		data: { text: buffer }
+	});
+	return trimBoundaryTextSegments(segments);
+}
+function isTextSegment(segment) {
+	return segment.type === "text";
+}
+function withText(segment, text) {
+	return {
+		...segment,
+		data: {
+			...segment.data,
+			text
+		}
+	};
+}
+function trimBoundaryTextSegments(segments) {
+	const result = [...segments];
+	const first = result[0];
+	if (first && isTextSegment(first)) {
+		const text = first.data.text.trimStart();
+		if (text) result[0] = withText(first, text);
+		else result.shift();
+	}
+	const lastIndex = result.length - 1;
+	const last = result[lastIndex];
+	if (last && isTextSegment(last)) {
+		const text = last.data.text.trimEnd();
+		if (text) result[lastIndex] = withText(last, text);
+		else result.pop();
+	}
+	return result;
+}
+let seg;
+(function(_seg) {
+	function mention(userId) {
+		return {
+			type: "mention",
+			data: { user_id: userId }
+		};
+	}
+	_seg.mention = mention;
+	function mentionAll() {
+		return {
+			type: "mention_all",
+			data: {}
+		};
+	}
+	_seg.mentionAll = mentionAll;
+	function face(faceId, options) {
+		return {
+			type: "face",
+			data: {
+				face_id: faceId.toString(),
+				is_large: options?.isLarge ?? false
+			}
+		};
+	}
+	_seg.face = face;
+	function reply(messageSeq) {
+		return {
+			type: "reply",
+			data: { message_seq: messageSeq }
+		};
+	}
+	_seg.reply = reply;
+	function image(uri, options) {
+		return {
+			type: "image",
+			data: {
+				uri,
+				sub_type: options?.subType,
+				summary: options?.summary
+			}
+		};
+	}
+	_seg.image = image;
+	function record(uri) {
+		return {
+			type: "record",
+			data: { uri }
+		};
+	}
+	_seg.record = record;
+	function video(uri, options) {
+		return {
+			type: "video",
+			data: {
+				uri,
+				thumb_uri: options?.thumbUri
+			}
+		};
+	}
+	_seg.video = video;
+	function forward(messages, options) {
+		return {
+			type: "forward",
+			data: {
+				messages,
+				title: options?.title,
+				preview: options?.preview,
+				summary: options?.summary,
+				prompt: options?.prompt
+			}
+		};
+	}
+	_seg.forward = forward;
+})(seg || (seg = {}));
+//#endregion
 //#region src/routing/command.ts
 var CommandBuilder = class {
 	name;
 	sink;
 	pattern = {};
 	executor;
+	description;
+	aliases;
+	hidden;
 	constructor(name, sink = (command) => command) {
 		this.name = name;
 		this.sink = sink;
@@ -78,6 +213,19 @@ var CommandBuilder = class {
 		this.pattern[key] = parameter;
 		return this;
 	}
+	describe(description) {
+		this.description = description;
+		return this;
+	}
+	alias(...aliases) {
+		if (!this.aliases) this.aliases = [];
+		this.aliases.push(...aliases);
+		return this;
+	}
+	hide() {
+		this.hidden = true;
+		return this;
+	}
 	execute(executor) {
 		this.executor = executor;
 		const command = {
@@ -85,6 +233,9 @@ var CommandBuilder = class {
 			pattern: this.pattern,
 			execute: this.executor
 		};
+		if (this.description !== void 0) command.description = this.description;
+		if (this.aliases !== void 0) command.aliases = this.aliases;
+		if (this.hidden !== void 0) command.hidden = this.hidden;
 		return this.sink(command);
 	}
 };
@@ -222,6 +373,7 @@ var Router = class Router {
 			return builtCommand;
 		});
 		this.validatePattern(command.pattern);
+		this.resolveAliasConflicts(command);
 		this.entries.push({
 			type: "command",
 			command
@@ -265,6 +417,10 @@ var Router = class Router {
 	routes() {
 		return this.entries;
 	}
+	aliasesOf(name) {
+		for (const entry of this.entries) if (entry.type === "command" && entry.command.name === name) return entry.command.aliases ? [...entry.command.aliases] : [];
+		return [];
+	}
 	branches(session) {
 		return this.branchesFrom(session, []);
 	}
@@ -306,7 +462,7 @@ var Router = class Router {
 	}
 	matchCommand(command, tokenizer, path) {
 		const token = tokenizer.peek();
-		if (typeof token !== "string" || token !== command.name) return;
+		if (typeof token !== "string" || token !== command.name && !command.aliases?.includes(token)) return;
 		tokenizer.next();
 		const params = this.capturePattern(command.pattern, tokenizer);
 		if (params === void 0 || tokenizer.hasNext()) return;
@@ -337,7 +493,7 @@ var Router = class Router {
 		const branches = [];
 		for (const entry of this.entries) switch (entry.type) {
 			case "command":
-				branches.push({
+				if (!entry.command.hidden) branches.push({
 					type: "command",
 					path: [...path],
 					command: entry.command
@@ -359,6 +515,27 @@ var Router = class Router {
 		}
 		return branches;
 	}
+	resolveAliasConflicts(command) {
+		for (const entry of this.entries) {
+			if (entry.type !== "command") continue;
+			const existing = entry.command;
+			if (existing.aliases?.includes(command.name)) {
+				existing.aliases = existing.aliases.filter((a) => a !== command.name);
+				console.warn(`Command "${command.name}" conflicts with alias of existing command "${existing.name}". The alias "${command.name}" has been removed from "${existing.name}".`);
+			}
+			if (command.aliases) {
+				const dropped = [];
+				for (const alias of command.aliases) if (existing.name === alias) {
+					dropped.push(alias);
+					console.warn(`Alias "${alias}" of command "${command.name}" conflicts with existing command name "${existing.name}". The alias has been dropped.`);
+				} else if (existing.aliases?.includes(alias)) {
+					existing.aliases = existing.aliases.filter((a) => a !== alias);
+					console.warn(`Alias "${alias}" of command "${command.name}" conflicts with alias of existing command "${existing.name}". The alias has been removed from "${existing.name}".`);
+				}
+				if (dropped.length > 0) command.aliases = command.aliases.filter((a) => !dropped.includes(a));
+			}
+		}
+	}
 	validatePattern(pattern, options) {
 		const entries = Object.entries(pattern);
 		if (options?.rawPattern && entries.length === 0) throw new Error("Raw pattern must have at least one parameter.");
@@ -547,25 +724,35 @@ and implement the dispose method to clean up resources when the context stops.
 	createSession(message) {
 		return {
 			raw: message,
-			reply: async (segments) => {
-				try {
-					switch (message.message_scene) {
-						case "friend":
-							await this.client.send_private_message({
-								user_id: message.peer_id,
-								message: segments
-							});
-							break;
-						case "group":
-							await this.client.send_group_message({
-								group_id: message.peer_id,
-								message: segments
-							});
-							break;
+			reply: async (segments, options) => {
+				const actualSegments = [...segments];
+				if (options?.withMention && message.message_scene === "group") actualSegments.unshift(seg.mention(message.sender_id));
+				if (options?.withQuote) actualSegments.unshift(seg.reply(message.message_seq));
+				switch (message.message_scene) {
+					case "friend": {
+						const { message_seq } = await this.client.send_private_message({
+							user_id: message.peer_id,
+							message: actualSegments
+						});
+						return { messageSeq: message_seq };
+					}
+					case "group": {
+						const { message_seq } = await this.client.send_group_message({
+							group_id: message.peer_id,
+							message: actualSegments
+						});
+						return { messageSeq: message_seq };
 					}
-				} catch (error) {
-					this.logger.error(`Error sending reply (source msg: scene=${message.message_scene} peer=${message.peer_id} sender=${message.sender_id} seq=${message.message_seq})`, error);
 				}
+				return { messageSeq: 0 };
+			},
+			reaction: async (type, reactionId) => {
+				if (message.message_scene === "group") await this.client.send_group_message_reaction({
+					group_id: message.peer_id,
+					message_seq: message.message_seq,
+					reaction_type: type,
+					reaction: reactionId
+				});
 			}
 		};
 	}
@@ -681,7 +868,15 @@ and implement the dispose method to clean up resources when the context stops.
 		for (const installedPlugin of sortedPlugins) {
 			const { plugin, args } = installedPlugin;
 			const providedBeforeApply = new Set(this.services.keys());
-			this.logger.debug(`Applying plugin ${plugin.name}`);
+			let applyingMessage = `Applying plugin ${plugin.name}`;
+			const requiredServices = [];
+			const providedServices = [];
+			if (plugin.requires) for (const service of plugin.requires) requiredServices.push(service.name);
+			if (plugin.optionalRequires) for (const service of plugin.optionalRequires) requiredServices.push(`${service.name}?`);
+			if (plugin.provides) for (const service of plugin.provides) providedServices.push(service.name);
+			if (requiredServices.length > 0) applyingMessage += `, requires: [${requiredServices.join(", ")}]`;
+			if (providedServices.length > 0) applyingMessage += `, provides: [${providedServices.join(", ")}]`;
+			this.logger.info(applyingMessage);
 			await plugin.apply(this.getPluginContext(installedPlugin), ...args);
 			for (const service of plugin.provides ?? []) if (!this.services.has(service) || providedBeforeApply.has(service)) throw new Error(`${plugin.name} declares service ${service.name} but did not provide it.`);
 		}
@@ -780,10 +975,6 @@ and implement the dispose method to clean up resources when the context stops.
 	}
 	createProxyContextForPlugin(plugin) {
 		const proxyLogger = new Logger((message) => this.logHandler?.(message), plugin.name);
-		const proxyProvide = (service, instance) => {
-			this.provide(service, instance);
-			this.logger.debug(`Plugin ${plugin.name} provided ${service.name}`);
-		};
 		let proxyInjections;
 		if (plugin.inject) {
 			proxyInjections = {};
@@ -795,7 +986,6 @@ and implement the dispose method to clean up resources when the context stops.
 		}
 		return new Proxy(this, { get(target, prop, receiver) {
 			if (prop === "logger") return proxyLogger;
-			else if (prop === "provide") return proxyProvide;
 			else if (proxyInjections && prop in proxyInjections) return proxyInjections[prop];
 			else return Reflect.get(target, prop, receiver);
 		} });
@@ -1015,138 +1205,6 @@ function definePlugin(plugin) {
 	return plugin;
 }
 //#endregion
-//#region src/protocol/segment.ts
-function msg(strings, ...values) {
-	let buffer = "";
-	const segments = [];
-	for (let i = 0; i < strings.length; i++) {
-		buffer += strings[i];
-		if (i < values.length) {
-			const value = values[i];
-			if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") buffer += value.toString();
-			else {
-				if (buffer) {
-					segments.push({
-						type: "text",
-						data: { text: buffer }
-					});
-					buffer = "";
-				}
-				segments.push(value);
-			}
-		}
-	}
-	if (buffer) segments.push({
-		type: "text",
-		data: { text: buffer }
-	});
-	return trimBoundaryTextSegments(segments);
-}
-function isTextSegment(segment) {
-	return segment.type === "text";
-}
-function withText(segment, text) {
-	return {
-		...segment,
-		data: {
-			...segment.data,
-			text
-		}
-	};
-}
-function trimBoundaryTextSegments(segments) {
-	const result = [...segments];
-	const first = result[0];
-	if (first && isTextSegment(first)) {
-		const text = first.data.text.trimStart();
-		if (text) result[0] = withText(first, text);
-		else result.shift();
-	}
-	const lastIndex = result.length - 1;
-	const last = result[lastIndex];
-	if (last && isTextSegment(last)) {
-		const text = last.data.text.trimEnd();
-		if (text) result[lastIndex] = withText(last, text);
-		else result.pop();
-	}
-	return result;
-}
-let seg;
-(function(_seg) {
-	function mention(userId) {
-		return {
-			type: "mention",
-			data: { user_id: userId }
-		};
-	}
-	_seg.mention = mention;
-	function mentionAll() {
-		return {
-			type: "mention_all",
-			data: {}
-		};
-	}
-	_seg.mentionAll = mentionAll;
-	function face(faceId, options) {
-		return {
-			type: "face",
-			data: {
-				face_id: faceId.toString(),
-				is_large: options?.isLarge ?? false
-			}
-		};
-	}
-	_seg.face = face;
-	function reply(messageSeq) {
-		return {
-			type: "reply",
-			data: { message_seq: messageSeq }
-		};
-	}
-	_seg.reply = reply;
-	function image(uri, options) {
-		return {
-			type: "image",
-			data: {
-				uri,
-				sub_type: options?.subType,
-				summary: options?.summary
-			}
-		};
-	}
-	_seg.image = image;
-	function record(uri) {
-		return {
-			type: "record",
-			data: { uri }
-		};
-	}
-	_seg.record = record;
-	function video(uri, options) {
-		return {
-			type: "video",
-			data: {
-				uri,
-				thumb_uri: options?.thumbUri
-			}
-		};
-	}
-	_seg.video = video;
-	function forward(messages, options) {
-		return {
-			type: "forward",
-			data: {
-				messages,
-				title: options?.title,
-				preview: options?.preview,
-				summary: options?.summary,
-				prompt: options?.prompt
-			}
-		};
-	}
-	_seg.forward = forward;
-})(seg || (seg = {}));
-//#endregion
 //#region src/protocol/types.ts
 const milkyVersion = "1.3";
 const milkyPackageVersion = "1.3.0-rc.1";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fraqjs/fraq",
   "type": "module",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Milky Bot framework",
   "files": [
     "dist"