@fraqjs/plugin-mock 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,203 @@
+import { AnyApiCall, Context, ContextOptions, LogHandler, MilkyEventSource, MilkyEventSubscription, milky } from "@fraqjs/fraq";
+//#region src/entity.d.ts
+interface RandomFriendOverrides extends Partial<Omit<milky.FriendEntity, 'category'>> {
+  category?: Partial<milky.FriendCategoryEntity>;
+}
+interface RandomGroupOverrides extends Partial<milky.GroupEntity> {}
+interface RandomGroupMemberOverrides extends Partial<milky.GroupMemberEntity> {}
+declare function createRandomFriend(userId: number, overrides?: RandomFriendOverrides): milky.FriendEntity;
+declare function createRandomGroup(groupId: number, overrides?: RandomGroupOverrides): milky.GroupEntity;
+declare function createRandomGroupMember(groupId: number, userId: number, overrides?: RandomGroupMemberOverrides): milky.GroupMemberEntity;
+//#endregion
+//#region src/inbox.d.ts
+type MockMessageScene = 'friend' | 'group' | 'temp';
+interface MockMessageContext {
+  scene: MockMessageScene;
+  peerId: number;
+  senderId: number;
+  groupId?: number | undefined;
+}
+interface MockInboxOptions {
+  selfId?: number;
+  baseTime?: number;
+  sequenceStart?: number;
+  timeStepSeconds?: number;
+  conversationKey?(context: MockMessageContext): string;
+}
+interface MockMessageMetaOverrides {
+  messageSeq?: number;
+  time?: number;
+}
+interface MockFriendMessageOptions extends MockMessageMetaOverrides {
+  userId: number;
+  peerId?: number;
+  senderId?: number;
+  friend?: RandomFriendOverrides;
+}
+interface MockGroupMessageOptions extends MockMessageMetaOverrides {
+  groupId: number;
+  userId: number;
+  senderId?: number;
+  group?: RandomGroupOverrides;
+  groupMember?: RandomGroupMemberOverrides;
+}
+interface MockTempMessageOptions extends MockMessageMetaOverrides {
+  userId: number;
+  peerId?: number;
+  senderId?: number;
+  groupId?: number;
+  group?: RandomGroupOverrides | null;
+}
+interface MockMessageEventOverrides {
+  time?: number;
+  selfId?: number;
+}
+declare class MockInbox {
+  readonly selfId: number;
+  private readonly baseTime;
+  private readonly sequenceStart;
+  private readonly timeStepSeconds;
+  private readonly conversationKeyOf;
+  private readonly conversations;
+  private readonly allMessages;
+  private readonly friends;
+  private readonly groups;
+  private readonly groupMembers;
+  constructor(options?: MockInboxOptions);
+  conversationKey(context: MockMessageContext): string;
+  friendConversationKey(peerId: number, senderId?: number): string;
+  groupConversationKey(groupId: number, senderId?: number): string;
+  tempConversationKey(options: {
+    peerId?: number;
+    senderId: number;
+    groupId?: number;
+  }): string;
+  friend(options: MockFriendMessageOptions, segments: readonly milky.IncomingSegment_ZodInput[] | readonly milky.IncomingSegment[]): milky.IncomingFriendMessage;
+  group(options: MockGroupMessageOptions, segments: readonly milky.IncomingSegment_ZodInput[] | readonly milky.IncomingSegment[]): milky.IncomingGroupMessage;
+  temp(options: MockTempMessageOptions, segments: readonly milky.IncomingSegment_ZodInput[] | readonly milky.IncomingSegment[]): milky.IncomingTempMessage;
+  event(message: milky.IncomingMessage, overrides?: MockMessageEventOverrides): milky.MessageReceiveEvent;
+  friendEvent(options: MockFriendMessageOptions, segments: readonly milky.IncomingSegment_ZodInput[] | readonly milky.IncomingSegment[], overrides?: MockMessageEventOverrides): milky.MessageReceiveEvent;
+  groupEvent(options: MockGroupMessageOptions, segments: readonly milky.IncomingSegment_ZodInput[] | readonly milky.IncomingSegment[], overrides?: MockMessageEventOverrides): milky.MessageReceiveEvent;
+  tempEvent(options: MockTempMessageOptions, segments: readonly milky.IncomingSegment_ZodInput[] | readonly milky.IncomingSegment[], overrides?: MockMessageEventOverrides): milky.MessageReceiveEvent;
+  message(conversationKey: string, messageSeq: number): milky.IncomingMessage | undefined;
+  getMessage(input: milky.GetMessageInput_ZodInput): milky.GetMessageOutput;
+  getHistoryMessages(input: milky.GetHistoryMessagesInput_ZodInput): milky.GetHistoryMessagesOutput;
+  markMessageAsRead(input: milky.MarkMessageAsReadInput_ZodInput): milky.MarkMessageAsReadOutput;
+  getFriendInfo(input: milky.GetFriendInfoInput_ZodInput): milky.GetFriendInfoOutput;
+  getGroupInfo(input: milky.GetGroupInfoInput_ZodInput): milky.GetGroupInfoOutput;
+  getGroupMemberInfo(input: milky.GetGroupMemberInfoInput_ZodInput): milky.GetGroupMemberInfoOutput;
+  history(conversationKey?: string): milky.IncomingMessage[];
+  lastMessage(conversationKey?: string): milky.IncomingMessage | undefined;
+  reset(): void;
+  private allocateMessageMeta;
+  private getOrCreateConversationState;
+  private storeMessage;
+  private queryConversationKey;
+}
+declare function createMockInbox(options?: MockInboxOptions): MockInbox;
+//#endregion
+//#region src/service.d.ts
+interface MockApiCall {
+  endpoint: string;
+  params?: unknown;
+}
+interface MockServiceOptions extends MockInboxOptions {
+  inbox?: MockInbox;
+}
+declare class MockService implements MilkyEventSource {
+  readonly name = "mock";
+  readonly inbox: MockInbox;
+  readonly apiCalls: MockApiCall[];
+  private onEvent;
+  private closeEventsResolver;
+  startEventCalls: number;
+  private nextStartError;
+  constructor(options?: MockServiceOptions);
+  start(handler: (event: milky.Event) => void | Promise<void>): Promise<MilkyEventSubscription>;
+  closeEvents(): void;
+  failNextStart(error: unknown): void;
+  emitEvent(event: milky.Event): Promise<void>;
+  receiveFriend(options: MockFriendMessageOptions, segments: readonly milky.IncomingSegment_ZodInput[] | readonly milky.IncomingSegment[]): Promise<milky.IncomingFriendMessage>;
+  receiveGroup(options: MockGroupMessageOptions, segments: readonly milky.IncomingSegment_ZodInput[] | readonly milky.IncomingSegment[]): Promise<milky.IncomingGroupMessage>;
+  receiveTemp(options: MockTempMessageOptions, segments: readonly milky.IncomingSegment_ZodInput[] | readonly milky.IncomingSegment[]): Promise<milky.IncomingTempMessage>;
+  handleApiCall(call: AnyApiCall): unknown;
+  reset(): void;
+}
+//#endregion
+//#region src/logging.d.ts
+declare function createSimpleLogHandler(): LogHandler;
+//#endregion
+//#region src/message.d.ts
+type InmsgTemplateValue = string | number | boolean | milky.IncomingSegment_ZodInput;
+interface IncomingReplySource {
+  message_seq: number;
+  sender_id: number;
+  sender_name?: string | null | undefined;
+  time: number;
+  segments: milky.IncomingSegment[] | milky.IncomingSegment_ZodInput[];
+}
+declare function inmsg(strings: TemplateStringsArray, ...values: InmsgTemplateValue[]): milky.IncomingSegment_ZodInput[];
+declare namespace inseg {
+  function text(text: string): milky.IncomingTextSegment_ZodInput;
+  function mention(userId: number, name?: string): milky.IncomingMentionSegment_ZodInput;
+  function mentionAll(): milky.IncomingMentionAllSegment_ZodInput;
+  function face(faceId: number | string, options?: {
+    isLarge?: boolean;
+  }): milky.IncomingFaceSegment_ZodInput;
+  function reply(source: milky.IncomingMessage | IncomingReplySource): milky.IncomingReplySegment_ZodInput;
+  function image(options?: {
+    resourceId?: string;
+    tempUrl?: string;
+    width?: number;
+    height?: number;
+    summary?: string;
+    subType?: 'normal' | 'sticker';
+  }): milky.IncomingImageSegment_ZodInput;
+  function record(options?: {
+    resourceId?: string;
+    tempUrl?: string;
+    duration?: number;
+  }): milky.IncomingRecordSegment_ZodInput;
+  function video(options?: {
+    resourceId?: string;
+    tempUrl?: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+  }): milky.IncomingVideoSegment_ZodInput;
+  function file(options?: {
+    fileId?: string;
+    fileName?: string;
+    fileSize?: number;
+    fileHash?: string | null;
+  }): milky.IncomingFileSegment_ZodInput;
+  function forward(options?: {
+    forwardId?: string;
+    title?: string;
+    preview?: string[];
+    summary?: string;
+  }): milky.IncomingForwardSegment_ZodInput;
+  function marketFace(options?: {
+    emojiPackageId?: number;
+    emojiId?: string;
+    key?: string;
+    summary?: string;
+    url?: string;
+  }): milky.IncomingMarketFaceSegment_ZodInput;
+  function lightApp(appName: string, jsonPayload: string): milky.IncomingLightAppSegment_ZodInput;
+  function xml(serviceId: number, xmlPayload: string): milky.IncomingXmlSegment_ZodInput;
+  function markdown(content: string): milky.IncomingMarkdownSegment_ZodInput;
+}
+//#endregion
+//#region src/index.d.ts
+interface MockPluginOptions extends MockServiceOptions {
+  service?: MockService;
+}
+declare const MockPlugin: import("@fraqjs/fraq").Plugin<[options?: MockPluginOptions | undefined], import("@fraqjs/fraq").Injection | undefined, import("@fraqjs/fraq").Injection | undefined>;
+type MockContext = Context & {
+  readonly mock: MockService;
+};
+interface MockContextOptions extends MockServiceOptions, ContextOptions {}
+declare function createMockContext(options?: MockContextOptions): MockContext;
+//#endregion
+export { IncomingReplySource, InmsgTemplateValue, MockApiCall, MockContext, MockContextOptions, MockFriendMessageOptions, MockGroupMessageOptions, MockInbox, MockInboxOptions, MockMessageContext, MockMessageEventOverrides, MockMessageMetaOverrides, MockMessageScene, MockPlugin, MockPlugin as default, MockPluginOptions, MockService, MockServiceOptions, MockTempMessageOptions, RandomFriendOverrides, RandomGroupMemberOverrides, RandomGroupOverrides, createMockContext, createMockInbox, createRandomFriend, createRandomGroup, createRandomGroupMember, createSimpleLogHandler, inmsg, inseg };

package/dist/index.mjs

@@ -0,0 +1,1070 @@
+import { Context, definePlugin } from "@fraqjs/fraq";
+//#region src/logging.ts
+function createSimpleLogHandler() {
+	return ({ time, level, module, message, error }) => {
+		const timeStr = new Date(time).toISOString();
+		const levelStr = level.toUpperCase();
+		console.log(`[${timeStr} ${levelStr}] [${module}] ${message}`);
+		if (error) console.error(error);
+	};
+}
+//#endregion
+//#region src/random.ts
+const PCG32_MULTIPLIER = 6364136223846793005n;
+const UINT64_MASK = (1n << 64n) - 1n;
+const UINT32_MODULUS = 2 ** 32;
+function rotateRight32(value, rotation) {
+	const amount = rotation & 31;
+	if (amount === 0) return value >>> 0;
+	return (value >>> amount | value << 32 - amount) >>> 0;
+}
+var PCG32 = class {
+	state;
+	increment;
+	constructor(seed, sequence = 1n) {
+		this.state = 0n;
+		this.increment = (sequence << 1n | 1n) & UINT64_MASK;
+		this.nextUint32();
+		this.state = this.state + seed & UINT64_MASK;
+		this.nextUint32();
+	}
+	nextUint32() {
+		const currentState = this.state;
+		this.state = currentState * PCG32_MULTIPLIER + this.increment & UINT64_MASK;
+		return rotateRight32(Number((currentState >> 18n ^ currentState) >> 27n & 4294967295n), Number(currentState >> 59n & 31n));
+	}
+};
+function assertSafeInteger$1(value, name) {
+	if (!Number.isSafeInteger(value)) throw new RangeError(`${name} must be a safe integer.`);
+}
+var SeededRandom = class {
+	generator;
+	constructor(seed) {
+		assertSafeInteger$1(seed, "seed");
+		this.generator = new PCG32(BigInt(seed >>> 0));
+	}
+	uint32() {
+		return this.generator.nextUint32();
+	}
+	float() {
+		return this.uint32() / UINT32_MODULUS;
+	}
+	bool(probability = .5) {
+		return this.float() < probability;
+	}
+	int(minOrMax, maxExclusive) {
+		const minInclusive = maxExclusive === void 0 ? 0 : minOrMax;
+		const actualMaxExclusive = maxExclusive ?? minOrMax;
+		assertSafeInteger$1(minInclusive, "minInclusive");
+		assertSafeInteger$1(actualMaxExclusive, "maxExclusive");
+		if (actualMaxExclusive <= minInclusive) throw new RangeError("maxExclusive must be greater than minInclusive.");
+		const span = actualMaxExclusive - minInclusive;
+		const limit = Math.floor(UINT32_MODULUS / span) * span;
+		let value = this.uint32();
+		while (value >= limit) value = this.uint32();
+		return minInclusive + value % span;
+	}
+	range(minInclusive, maxInclusive) {
+		assertSafeInteger$1(minInclusive, "minInclusive");
+		assertSafeInteger$1(maxInclusive, "maxInclusive");
+		if (maxInclusive < minInclusive) throw new RangeError("maxInclusive must be greater than or equal to minInclusive.");
+		return minInclusive + this.int(maxInclusive - minInclusive + 1);
+	}
+	pick(items) {
+		if (items.length === 0) throw new RangeError("items must not be empty.");
+		return items[this.int(items.length)];
+	}
+	weightedPick(items, weightOf) {
+		if (items.length === 0) throw new RangeError("items must not be empty.");
+		let totalWeight = 0;
+		for (const item of items) totalWeight += weightOf(item);
+		const target = this.float() * totalWeight;
+		let cumulative = 0;
+		for (const item of items) {
+			cumulative += weightOf(item);
+			if (target < cumulative) return item;
+		}
+		return items[items.length - 1];
+	}
+};
+//#endregion
+//#region src/vocabulary.json
+var friend = {
+	"firstNames": [
+		"Alice",
+		"Bob",
+		"Carol",
+		"Dave",
+		"Eve",
+		"Frank",
+		"Grace",
+		"Heidi",
+		"Ivan",
+		"Judy",
+		"Mallory",
+		"Niaj",
+		"Olivia",
+		"Peggy",
+		"Rupert",
+		"Sybil",
+		"Trent",
+		"Victor",
+		"Walter",
+		"Zoe"
+	],
+	"lastNames": [
+		"Ash",
+		"Brook",
+		"Cedar",
+		"Dawn",
+		"Ember",
+		"Field",
+		"Grove",
+		"Harbor",
+		"Ivory",
+		"Jasper",
+		"Kite",
+		"Lake",
+		"Meadow",
+		"North",
+		"Oak",
+		"Pine",
+		"Quill",
+		"River",
+		"Stone",
+		"Vale"
+	],
+	"nicknameSuffixes": [
+		"",
+		"",
+		"",
+		"Nova",
+		"Pixel",
+		"Echo",
+		"Skylark",
+		"Comet",
+		"Drift",
+		"Aurora"
+	],
+	"remarks": [
+		"",
+		"",
+		"",
+		"Project lead",
+		"Design review",
+		"Ops contact",
+		"Weekend runner",
+		"Late-night debugger",
+		"Coffee strategist",
+		"Always online"
+	],
+	"categoryNames": [
+		"General",
+		"Work",
+		"Friends",
+		"Study",
+		"Gaming",
+		"Family",
+		"Local",
+		"Archive"
+	]
+};
+var group = {
+	"prefixes": [
+		"Northwind",
+		"Silver",
+		"Quiet",
+		"Golden",
+		"Blue",
+		"Rapid",
+		"Lucky",
+		"Open",
+		"Bright",
+		"Sunday"
+	],
+	"topics": [
+		"Studio",
+		"Workshop",
+		"Lab",
+		"Guild",
+		"Circle",
+		"Squad",
+		"Forum",
+		"Club",
+		"Corner",
+		"Channel"
+	],
+	"suffixes": [
+		"",
+		"",
+		"HQ",
+		"Room",
+		"Collective",
+		"Network",
+		"Union",
+		"Hub"
+	],
+	"remarks": [
+		"",
+		"",
+		"Pinned for testing",
+		"Quiet hours after midnight",
+		"Temporary coordination group",
+		"Read-only on weekends"
+	],
+	"descriptions": [
+		"A steady group for day-to-day coordination and practical discussion.",
+		"A relaxed place for updates, shared notes, and quick questions.",
+		"Used for planning, follow-up, and keeping small tasks moving.",
+		"A focused channel for experiments, reviews, and status checks.",
+		"A casual room where people trade ideas, links, and useful context."
+	],
+	"questions": [
+		"",
+		"",
+		"What are you hoping to work on here?",
+		"Who invited you to join this group?",
+		"Share one sentence about your role in this space."
+	],
+	"announcements": [
+		"Welcome aboard. Keep threads tidy and label follow-ups clearly.",
+		"Weekly review starts at 20:00. Bring blockers and next steps.",
+		"Please avoid duplicate questions; check the pinned notes first.",
+		"Files older than 30 days may be archived during cleanup.",
+		"Be kind, be direct, and leave enough context for the next person."
+	]
+};
+var groupMember = {
+	"cardPrefixes": [
+		"",
+		"",
+		"Lead",
+		"Deputy",
+		"Night",
+		"Field",
+		"On-call",
+		"Guest",
+		"Blue",
+		"Quiet"
+	],
+	"cardSuffixes": [
+		"",
+		"",
+		"Ops",
+		"Builder",
+		"Planner",
+		"Scout",
+		"Keeper",
+		"Pilot",
+		"Scribe",
+		"Watcher"
+	],
+	"titles": [
+		"",
+		"",
+		"",
+		"Early Bird",
+		"Bug Hunter",
+		"Note Keeper",
+		"Night Shift",
+		"Fast Responder",
+		"Steady Hand",
+		"Build Whisperer"
+	],
+	"levelLabels": [
+		"Sprout",
+		"Scout",
+		"Maker",
+		"Pilot",
+		"Anchor",
+		"Keeper",
+		"Guide",
+		"Expert"
+	]
+};
+//#endregion
+//#region src/entity.ts
+const ROLE_WEIGHTS = [
+	{
+		role: "owner",
+		weight: 1
+	},
+	{
+		role: "admin",
+		weight: 6
+	},
+	{
+		role: "member",
+		weight: 93
+	}
+];
+const SEX_WEIGHTS = [
+	{
+		sex: "male",
+		weight: 45
+	},
+	{
+		sex: "female",
+		weight: 45
+	},
+	{
+		sex: "unknown",
+		weight: 10
+	}
+];
+const GROUP_CAPACITY_TIERS = [
+	50,
+	100,
+	200,
+	500,
+	1e3,
+	2e3
+];
+const REFERENCE_TIME = Date.UTC(2025, 0, 1, 0, 0, 0) / 1e3;
+const GROUP_CREATED_TIME_START = Date.UTC(2018, 0, 1, 0, 0, 0) / 1e3;
+const GROUP_CREATED_TIME_END = Date.UTC(2024, 11, 31, 23, 59, 59) / 1e3;
+function assertSeedInput(value, name) {
+	if (!Number.isSafeInteger(value)) throw new RangeError(`${name} must be a safe integer.`);
+	return value;
+}
+function mixSeed(namespace, ...values) {
+	let hash = 2166136261;
+	for (const char of namespace) {
+		hash ^= char.charCodeAt(0);
+		hash = Math.imul(hash, 16777619) >>> 0;
+	}
+	for (const value of values) {
+		let current = assertSeedInput(value, "seed input") >>> 0;
+		for (let index = 0; index < 4; index += 1) {
+			hash ^= current & 255;
+			hash = Math.imul(hash, 16777619) >>> 0;
+			current >>>= 8;
+		}
+	}
+	return hash;
+}
+function createRandom(namespace, ...values) {
+	return new SeededRandom(mixSeed(namespace, ...values));
+}
+function joinParts(...parts) {
+	return parts.filter(Boolean).join(" ");
+}
+function createUserProfile(userId) {
+	const random = createRandom("friend-profile", userId);
+	const firstName = random.pick(friend.firstNames);
+	const lastName = random.pick(friend.lastNames);
+	const nicknameSuffix = random.pick(friend.nicknameSuffixes);
+	const sex = random.weightedPick(SEX_WEIGHTS, (item) => item.weight).sex;
+	return {
+		user_id: userId,
+		nickname: joinParts(firstName, lastName, nicknameSuffix),
+		sex,
+		qid: `qid_${Math.abs(userId).toString(36).padStart(6, "0")}`
+	};
+}
+function createFriendCategory(userId, overrides) {
+	const categoryId = createRandom("friend-category", userId).int(friend.categoryNames.length);
+	return {
+		category_id: categoryId + 1,
+		category_name: friend.categoryNames[categoryId],
+		...overrides
+	};
+}
+function createGroupBase(groupId) {
+	const random = createRandom("group", groupId);
+	const memberCount = random.range(12, 320);
+	const minCapacity = memberCount + random.range(0, 120);
+	const maxMemberCount = GROUP_CAPACITY_TIERS.find((capacity) => capacity >= minCapacity) ?? GROUP_CAPACITY_TIERS[GROUP_CAPACITY_TIERS.length - 1];
+	const createdTime = random.range(GROUP_CREATED_TIME_START, GROUP_CREATED_TIME_END);
+	return {
+		group_id: groupId,
+		group_name: joinParts(random.pick(group.prefixes), random.pick(group.topics), random.pick(group.suffixes)),
+		member_count: memberCount,
+		max_member_count: maxMemberCount,
+		remark: random.pick(group.remarks),
+		created_time: createdTime,
+		description: random.pick(group.descriptions),
+		question: random.pick(group.questions),
+		announcement: random.pick(group.announcements)
+	};
+}
+function createRandomFriend(userId, overrides = {}) {
+	assertSeedInput(userId, "userId");
+	const random = createRandom("friend", userId);
+	const friend$1 = {
+		...createUserProfile(userId),
+		remark: random.pick(friend.remarks),
+		category: createFriendCategory(userId, overrides.category)
+	};
+	return {
+		...friend$1,
+		...overrides,
+		category: {
+			...friend$1.category,
+			...overrides.category
+		}
+	};
+}
+function createRandomGroup(groupId, overrides = {}) {
+	assertSeedInput(groupId, "groupId");
+	return {
+		...createGroupBase(groupId),
+		...overrides
+	};
+}
+function createRandomGroupMember(groupId, userId, overrides = {}) {
+	assertSeedInput(groupId, "groupId");
+	assertSeedInput(userId, "userId");
+	const random = createRandom("group-member", groupId, userId);
+	const profile = createUserProfile(userId);
+	const group = createGroupBase(groupId);
+	const role = random.weightedPick(ROLE_WEIGHTS, (item) => item.weight).role;
+	const joinTimeEnd = Math.max(group.created_time, REFERENCE_TIME - 86400);
+	const joinTime = random.range(group.created_time, joinTimeEnd);
+	const lastSentTime = random.range(joinTime, REFERENCE_TIME);
+	const shutUpEndTime = random.bool(.1) ? lastSentTime + random.range(300, 10080 * 60) : null;
+	const cardPrefix = random.pick(groupMember.cardPrefixes);
+	const cardSuffix = random.pick(groupMember.cardSuffixes);
+	const card = joinParts(cardPrefix, profile.nickname, cardSuffix);
+	const title = random.pick(groupMember.titles);
+	return {
+		user_id: userId,
+		nickname: profile.nickname,
+		sex: profile.sex,
+		group_id: groupId,
+		card,
+		title,
+		level: random.range(1, 100),
+		role,
+		join_time: joinTime,
+		last_sent_time: lastSentTime,
+		shut_up_end_time: shutUpEndTime,
+		...overrides
+	};
+}
+//#endregion
+//#region src/inbox.ts
+const DEFAULT_BASE_TIME = Date.UTC(2025, 0, 1, 0, 0, 0) / 1e3;
+function assertSafeInteger(value, name) {
+	if (!Number.isSafeInteger(value)) throw new RangeError(`${name} must be a safe integer.`);
+}
+function assertPositiveInteger(value, name) {
+	assertSafeInteger(value, name);
+	if (value <= 0) throw new RangeError(`${name} must be a positive integer.`);
+}
+function cloneSegments(segments) {
+	return segments.map((segment) => {
+		switch (segment.type) {
+			case "reply": return {
+				...segment,
+				data: {
+					...segment.data,
+					segments: cloneSegments(segment.data.segments)
+				}
+			};
+			case "forward":
+			case "image":
+			case "record":
+			case "video":
+			case "file":
+			case "market_face":
+			case "light_app":
+			case "xml":
+			case "markdown":
+			case "mention":
+			case "mention_all":
+			case "face":
+			case "text": return {
+				...segment,
+				data: { ...segment.data }
+			};
+		}
+	});
+}
+function groupMemberKey(groupId, userId) {
+	return `${groupId}:${userId}`;
+}
+function defaultConversationKey(context) {
+	switch (context.scene) {
+		case "friend": return `friend:${context.peerId}`;
+		case "group": return `group:${context.groupId ?? context.peerId}`;
+		case "temp": return `temp:${context.groupId ?? context.peerId}:${context.senderId}`;
+	}
+}
+var MockInbox = class {
+	selfId;
+	baseTime;
+	sequenceStart;
+	timeStepSeconds;
+	conversationKeyOf;
+	conversations = /* @__PURE__ */ new Map();
+	allMessages = [];
+	friends = /* @__PURE__ */ new Map();
+	groups = /* @__PURE__ */ new Map();
+	groupMembers = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.selfId = options.selfId ?? 1e4;
+		this.baseTime = options.baseTime ?? DEFAULT_BASE_TIME;
+		this.sequenceStart = options.sequenceStart ?? 1;
+		this.timeStepSeconds = options.timeStepSeconds ?? 1;
+		this.conversationKeyOf = options.conversationKey ?? defaultConversationKey;
+		assertPositiveInteger(this.selfId, "selfId");
+		assertSafeInteger(this.baseTime, "baseTime");
+		assertPositiveInteger(this.sequenceStart, "sequenceStart");
+		assertPositiveInteger(this.timeStepSeconds, "timeStepSeconds");
+	}
+	conversationKey(context) {
+		if (context.groupId !== void 0) assertPositiveInteger(context.groupId, "groupId");
+		assertPositiveInteger(context.peerId, "peerId");
+		assertPositiveInteger(context.senderId, "senderId");
+		return this.conversationKeyOf(context);
+	}
+	friendConversationKey(peerId, senderId = peerId) {
+		assertPositiveInteger(peerId, "peerId");
+		assertPositiveInteger(senderId, "senderId");
+		return this.conversationKey({
+			scene: "friend",
+			peerId,
+			senderId
+		});
+	}
+	groupConversationKey(groupId, senderId = groupId) {
+		assertPositiveInteger(groupId, "groupId");
+		assertPositiveInteger(senderId, "senderId");
+		return this.conversationKey({
+			scene: "group",
+			peerId: groupId,
+			senderId,
+			groupId
+		});
+	}
+	tempConversationKey(options) {
+		const peerId = options.peerId ?? options.senderId;
+		assertPositiveInteger(peerId, "peerId");
+		assertPositiveInteger(options.senderId, "senderId");
+		if (options.groupId !== void 0) assertPositiveInteger(options.groupId, "groupId");
+		return this.conversationKey({
+			scene: "temp",
+			peerId,
+			senderId: options.senderId,
+			groupId: options.groupId
+		});
+	}
+	friend(options, segments) {
+		assertPositiveInteger(options.userId, "userId");
+		const peerId = options.peerId ?? options.userId;
+		const senderId = options.senderId ?? options.userId;
+		assertPositiveInteger(peerId, "peerId");
+		assertPositiveInteger(senderId, "senderId");
+		const conversationKey = this.conversationKey({
+			scene: "friend",
+			peerId,
+			senderId
+		});
+		const { messageSeq, time } = this.allocateMessageMeta(conversationKey, options);
+		const message = {
+			message_scene: "friend",
+			peer_id: peerId,
+			message_seq: messageSeq,
+			sender_id: senderId,
+			time,
+			segments: cloneSegments(segments),
+			friend: createRandomFriend(options.userId, options.friend)
+		};
+		this.storeMessage(conversationKey, message);
+		return message;
+	}
+	group(options, segments) {
+		assertPositiveInteger(options.groupId, "groupId");
+		assertPositiveInteger(options.userId, "userId");
+		const senderId = options.senderId ?? options.userId;
+		assertPositiveInteger(senderId, "senderId");
+		const conversationKey = this.conversationKey({
+			scene: "group",
+			peerId: options.groupId,
+			senderId,
+			groupId: options.groupId
+		});
+		const { messageSeq, time } = this.allocateMessageMeta(conversationKey, options);
+		const message = {
+			message_scene: "group",
+			peer_id: options.groupId,
+			message_seq: messageSeq,
+			sender_id: senderId,
+			time,
+			segments: cloneSegments(segments),
+			group: createRandomGroup(options.groupId, options.group),
+			group_member: createRandomGroupMember(options.groupId, options.userId, options.groupMember)
+		};
+		this.storeMessage(conversationKey, message);
+		return message;
+	}
+	temp(options, segments) {
+		assertPositiveInteger(options.userId, "userId");
+		const peerId = options.peerId ?? options.userId;
+		const senderId = options.senderId ?? options.userId;
+		assertPositiveInteger(peerId, "peerId");
+		assertPositiveInteger(senderId, "senderId");
+		if (options.groupId !== void 0) assertPositiveInteger(options.groupId, "groupId");
+		const conversationKey = this.conversationKey({
+			scene: "temp",
+			peerId,
+			senderId,
+			groupId: options.groupId
+		});
+		const { messageSeq, time } = this.allocateMessageMeta(conversationKey, options);
+		const group = options.group === null ? null : options.groupId === void 0 ? void 0 : createRandomGroup(options.groupId, options.group);
+		const message = {
+			message_scene: "temp",
+			peer_id: peerId,
+			message_seq: messageSeq,
+			sender_id: senderId,
+			time,
+			segments: cloneSegments(segments),
+			group
+		};
+		this.storeMessage(conversationKey, message);
+		return message;
+	}
+	event(message, overrides) {
+		const eventTime = overrides?.time ?? message.time;
+		const selfId = overrides?.selfId ?? this.selfId;
+		assertSafeInteger(eventTime, "event time");
+		assertPositiveInteger(selfId, "event selfId");
+		return {
+			event_type: "message_receive",
+			time: eventTime,
+			self_id: selfId,
+			data: message
+		};
+	}
+	friendEvent(options, segments, overrides) {
+		return this.event(this.friend(options, segments), overrides);
+	}
+	groupEvent(options, segments, overrides) {
+		return this.event(this.group(options, segments), overrides);
+	}
+	tempEvent(options, segments, overrides) {
+		return this.event(this.temp(options, segments), overrides);
+	}
+	message(conversationKey, messageSeq) {
+		return this.conversations.get(conversationKey)?.bySeq.get(messageSeq);
+	}
+	getMessage(input) {
+		const conversationKey = this.queryConversationKey(input.message_scene, input.peer_id);
+		const message = this.message(conversationKey, input.message_seq);
+		if (!message) throw new Error(`Message not found (scene=${input.message_scene} peer=${input.peer_id} seq=${input.message_seq})`);
+		return { message };
+	}
+	getHistoryMessages(input) {
+		const conversationKey = this.queryConversationKey(input.message_scene, input.peer_id);
+		const limit = input.limit ?? 30;
+		const startMessageSeq = input.start_message_seq;
+		assertPositiveInteger(limit, "limit");
+		if (limit > 30) throw new RangeError("limit must be less than or equal to 30.");
+		const messages = this.history(conversationKey);
+		const endIndex = startMessageSeq == null ? messages.length : messages.findIndex((message) => message.message_seq > startMessageSeq);
+		const boundedMessages = endIndex === -1 ? messages : messages.slice(0, endIndex);
+		const startIndex = Math.max(0, boundedMessages.length - limit);
+		return {
+			messages: boundedMessages.slice(startIndex),
+			next_message_seq: boundedMessages[startIndex - 1]?.message_seq
+		};
+	}
+	markMessageAsRead(input) {
+		if (input.message_scene === "temp") return {};
+		const conversationKey = this.queryConversationKey(input.message_scene, input.peer_id);
+		const state = this.getOrCreateConversationState(conversationKey);
+		state.lastReadMessageSeq = input.message_seq;
+		return {};
+	}
+	getFriendInfo(input) {
+		assertPositiveInteger(input.user_id, "user_id");
+		return { friend: this.friends.get(input.user_id) ?? createRandomFriend(input.user_id) };
+	}
+	getGroupInfo(input) {
+		assertPositiveInteger(input.group_id, "group_id");
+		return { group: this.groups.get(input.group_id) ?? createRandomGroup(input.group_id) };
+	}
+	getGroupMemberInfo(input) {
+		assertPositiveInteger(input.group_id, "group_id");
+		assertPositiveInteger(input.user_id, "user_id");
+		const key = groupMemberKey(input.group_id, input.user_id);
+		return { member: this.groupMembers.get(key) ?? createRandomGroupMember(input.group_id, input.user_id) };
+	}
+	history(conversationKey) {
+		if (conversationKey === void 0) return [...this.allMessages];
+		return [...this.conversations.get(conversationKey)?.messages ?? []];
+	}
+	lastMessage(conversationKey) {
+		return this.history(conversationKey).at(-1);
+	}
+	reset() {
+		this.conversations.clear();
+		this.allMessages.length = 0;
+		this.friends.clear();
+		this.groups.clear();
+		this.groupMembers.clear();
+	}
+	allocateMessageMeta(conversationKey, overrides) {
+		const state = this.getOrCreateConversationState(conversationKey);
+		const messageSeq = overrides.messageSeq ?? state.nextSeq;
+		const time = overrides.time ?? state.nextTime;
+		assertPositiveInteger(messageSeq, "messageSeq");
+		assertSafeInteger(time, "time");
+		state.nextSeq = Math.max(state.nextSeq, messageSeq + 1);
+		state.nextTime = Math.max(state.nextTime, time + this.timeStepSeconds);
+		return {
+			messageSeq,
+			time
+		};
+	}
+	getOrCreateConversationState(conversationKey) {
+		let state = this.conversations.get(conversationKey);
+		if (!state) {
+			state = {
+				nextSeq: this.sequenceStart,
+				nextTime: this.baseTime,
+				messages: [],
+				bySeq: /* @__PURE__ */ new Map(),
+				lastReadMessageSeq: void 0
+			};
+			this.conversations.set(conversationKey, state);
+		}
+		return state;
+	}
+	storeMessage(conversationKey, message) {
+		const state = this.getOrCreateConversationState(conversationKey);
+		state.messages.push(message);
+		state.bySeq.set(message.message_seq, message);
+		this.allMessages.push(message);
+		switch (message.message_scene) {
+			case "friend":
+				this.friends.set(message.friend.user_id, message.friend);
+				break;
+			case "group":
+				this.groups.set(message.group.group_id, message.group);
+				this.groupMembers.set(groupMemberKey(message.group_member.group_id, message.group_member.user_id), message.group_member);
+				break;
+			case "temp":
+				if (message.group) this.groups.set(message.group.group_id, message.group);
+				break;
+		}
+	}
+	queryConversationKey(scene, peerId) {
+		assertPositiveInteger(peerId, "peer_id");
+		switch (scene) {
+			case "friend": return this.friendConversationKey(peerId);
+			case "group": return this.groupConversationKey(peerId);
+			case "temp": throw new Error("Temporary message queries are not supported.");
+		}
+	}
+};
+function createMockInbox(options) {
+	return new MockInbox(options);
+}
+//#endregion
+//#region src/service.ts
+var MockService = class {
+	name = "mock";
+	inbox;
+	apiCalls = [];
+	onEvent;
+	closeEventsResolver;
+	startEventCalls = 0;
+	nextStartError;
+	constructor(options = {}) {
+		this.inbox = options.inbox ?? new MockInbox(options);
+	}
+	async start(handler) {
+		this.startEventCalls += 1;
+		if (this.nextStartError) {
+			const error = this.nextStartError;
+			this.nextStartError = void 0;
+			throw error;
+		}
+		this.onEvent = handler;
+		return {
+			closed: new Promise((resolve) => {
+				this.closeEventsResolver = resolve;
+			}),
+			stop: () => {
+				this.closeEvents();
+			}
+		};
+	}
+	closeEvents() {
+		this.closeEventsResolver?.();
+		this.closeEventsResolver = void 0;
+		this.onEvent = void 0;
+	}
+	failNextStart(error) {
+		this.nextStartError = error;
+	}
+	async emitEvent(event) {
+		await this.onEvent?.(event);
+	}
+	async receiveFriend(options, segments) {
+		const event = this.inbox.friendEvent(options, segments);
+		await this.emitEvent(event);
+		return event.data;
+	}
+	async receiveGroup(options, segments) {
+		const event = this.inbox.groupEvent(options, segments);
+		await this.emitEvent(event);
+		return event.data;
+	}
+	async receiveTemp(options, segments) {
+		const event = this.inbox.tempEvent(options, segments);
+		await this.emitEvent(event);
+		return event.data;
+	}
+	handleApiCall(call) {
+		this.apiCalls.push({
+			endpoint: call.endpoint,
+			params: call.params
+		});
+		const params = call.params;
+		switch (call.endpoint) {
+			case "get_message": return this.inbox.getMessage(params);
+			case "get_history_messages": return this.inbox.getHistoryMessages(params);
+			case "mark_message_as_read": return this.inbox.markMessageAsRead(params);
+			case "get_friend_info": return this.inbox.getFriendInfo(params);
+			case "get_group_info": return this.inbox.getGroupInfo(params);
+			case "get_group_member_info": return this.inbox.getGroupMemberInfo(params);
+			default: return {};
+		}
+	}
+	reset() {
+		this.apiCalls.length = 0;
+		this.inbox.reset();
+	}
+};
+//#endregion
+//#region src/message.ts
+function inmsg(strings, ...values) {
+	let buffer = "";
+	const segments = [];
+	for (let index = 0; index < strings.length; index += 1) {
+		buffer += strings[index];
+		if (index >= values.length) continue;
+		const value = values[index];
+		if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+			buffer += value.toString();
+			continue;
+		}
+		if (buffer) {
+			segments.push(inseg.text(buffer));
+			buffer = "";
+		}
+		segments.push(value);
+	}
+	if (buffer) segments.push(inseg.text(buffer));
+	return trimBoundaryTextSegments(segments);
+}
+function trimBoundaryTextSegments(segments) {
+	const result = [...segments];
+	const first = result[0];
+	if (first?.type === "text") {
+		const text = first.data.text.trimStart();
+		if (text) result[0] = inseg.text(text);
+		else result.shift();
+	}
+	const lastIndex = result.length - 1;
+	const last = result[lastIndex];
+	if (last?.type === "text") {
+		const text = last.data.text.trimEnd();
+		if (text) result[lastIndex] = inseg.text(text);
+		else result.pop();
+	}
+	return result;
+}
+let inseg;
+(function(_inseg) {
+	function text(text) {
+		return {
+			type: "text",
+			data: { text }
+		};
+	}
+	_inseg.text = text;
+	function mention(userId, name = `user_${userId}`) {
+		return {
+			type: "mention",
+			data: {
+				user_id: userId,
+				name
+			}
+		};
+	}
+	_inseg.mention = mention;
+	function mentionAll() {
+		return {
+			type: "mention_all",
+			data: {}
+		};
+	}
+	_inseg.mentionAll = mentionAll;
+	function face(faceId, options) {
+		return {
+			type: "face",
+			data: {
+				face_id: faceId.toString(),
+				is_large: options?.isLarge ?? false
+			}
+		};
+	}
+	_inseg.face = face;
+	function reply(source) {
+		const data = "message_scene" in source ? {
+			message_seq: source.message_seq,
+			sender_id: source.sender_id,
+			sender_name: void 0,
+			time: source.time,
+			segments: source.segments
+		} : source;
+		return {
+			type: "reply",
+			data: {
+				message_seq: data.message_seq,
+				sender_id: data.sender_id,
+				sender_name: data.sender_name,
+				time: data.time,
+				segments: [...data.segments]
+			}
+		};
+	}
+	_inseg.reply = reply;
+	function image(options) {
+		return {
+			type: "image",
+			data: {
+				resource_id: options?.resourceId ?? "mock-image",
+				temp_url: options?.tempUrl ?? "https://example.invalid/mock-image",
+				width: options?.width ?? 640,
+				height: options?.height ?? 480,
+				summary: options?.summary ?? "[image]",
+				sub_type: options?.subType ?? "normal"
+			}
+		};
+	}
+	_inseg.image = image;
+	function record(options) {
+		return {
+			type: "record",
+			data: {
+				resource_id: options?.resourceId ?? "mock-record",
+				temp_url: options?.tempUrl ?? "https://example.invalid/mock-record",
+				duration: options?.duration ?? 3
+			}
+		};
+	}
+	_inseg.record = record;
+	function video(options) {
+		return {
+			type: "video",
+			data: {
+				resource_id: options?.resourceId ?? "mock-video",
+				temp_url: options?.tempUrl ?? "https://example.invalid/mock-video",
+				width: options?.width ?? 1280,
+				height: options?.height ?? 720,
+				duration: options?.duration ?? 12
+			}
+		};
+	}
+	_inseg.video = video;
+	function file(options) {
+		return {
+			type: "file",
+			data: {
+				file_id: options?.fileId ?? "mock-file",
+				file_name: options?.fileName ?? "mock.txt",
+				file_size: options?.fileSize ?? 1024,
+				file_hash: options?.fileHash
+			}
+		};
+	}
+	_inseg.file = file;
+	function forward(options) {
+		return {
+			type: "forward",
+			data: {
+				forward_id: options?.forwardId ?? "mock-forward",
+				title: options?.title ?? "Chat History",
+				preview: options?.preview ?? ["Alice: ping", "Bob: pong"],
+				summary: options?.summary ?? "View forwarded messages"
+			}
+		};
+	}
+	_inseg.forward = forward;
+	function marketFace(options) {
+		return {
+			type: "market_face",
+			data: {
+				emoji_package_id: options?.emojiPackageId ?? 1,
+				emoji_id: options?.emojiId ?? "mock-market-face",
+				key: options?.key ?? "mock-key",
+				summary: options?.summary ?? "[market face]",
+				url: options?.url ?? "https://example.invalid/mock-market-face"
+			}
+		};
+	}
+	_inseg.marketFace = marketFace;
+	function lightApp(appName, jsonPayload) {
+		return {
+			type: "light_app",
+			data: {
+				app_name: appName,
+				json_payload: jsonPayload
+			}
+		};
+	}
+	_inseg.lightApp = lightApp;
+	function xml(serviceId, xmlPayload) {
+		return {
+			type: "xml",
+			data: {
+				service_id: serviceId,
+				xml_payload: xmlPayload
+			}
+		};
+	}
+	_inseg.xml = xml;
+	function markdown(content) {
+		return {
+			type: "markdown",
+			data: { content }
+		};
+	}
+	_inseg.markdown = markdown;
+})(inseg || (inseg = {}));
+//#endregion
+//#region src/index.ts
+function installMock(ctx, service) {
+	ctx.hookApi((call) => service.handleApiCall(call));
+	ctx.installEventSource(service);
+	ctx.provide(MockService, service);
+	return service;
+}
+const MockPlugin = definePlugin({
+	name: "mock",
+	provides: [MockService],
+	apply(ctx, options) {
+		installMock(ctx, options?.service ?? new MockService(options));
+	}
+});
+const unreachableClient = new Proxy({}, { get(_target, prop) {
+	if (typeof prop === "string" && prop.includes("_")) return () => {
+		throw new Error(`[plugin-mock] API "${prop}" fell through to the stub client.`);
+	};
+} });
+function createMockContext(options) {
+	const ctx = Context.fromClient(unreachableClient, {
+		...options,
+		logHandler: options?.logHandler ?? createSimpleLogHandler()
+	});
+	const mock = installMock(ctx, new MockService(options));
+	return Object.assign(ctx, { mock });
+}
+//#endregion
+export { MockInbox, MockPlugin, MockPlugin as default, MockService, createMockContext, createMockInbox, createRandomFriend, createRandomGroup, createRandomGroupMember, createSimpleLogHandler, inmsg, inseg };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@fraqjs/plugin-mock",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "提供模拟 Milky 协议端的能力，帮助开发者编写插件测试",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.mjs",
+  "typings": "dist/index.d.mts",
+  "keywords": [],
+  "author": "fraqjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fraqjs/fraq.git"
+  },
+  "homepage": "https://fraq.dev/docs/plugins/mock",
+  "license": "MIT",
+  "peerDependencies": {
+    "@fraqjs/fraq": "^0.14.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "fraq": {
+    "category": "infrastructure"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "tsx --test test/*.test.ts"
+  }
+}