@fraqjs/fraq 0.10.3 → 0.12.0

package/README.md

@@ -50,4 +50,4 @@ npx tsx index.ts
 
 上面的例子只是 Fraq 的最小使用方式，你还可以继续了解如何构造更丰富的消息、定义更复杂的指令参数、编写可复用的插件等。
 
-完整文档请见 [fraq.ntqqrev.org](https://fraq.ntqqrev.org/)。
+完整文档请见 [fraq.dev](https://fraq.dev/)。

package/dist/index.d.mts

@@ -405,7 +405,7 @@ declare namespace types_d_exports {
   };
 }
 declare const milkyVersion = '1.3';
-declare const milkyPackageVersion = '1.3.0-rc.1';
+declare const milkyPackageVersion = '1.3.0-rc.2';
 /** 机器人离线事件 */
 interface BotOfflineEvent {
   /** 数据类型区分字段，表示自身为机器人离线事件 */
@@ -2846,7 +2846,7 @@ interface GetImplInfoOutput {
     | 'iphone'
     | 'harmony'
     | 'watch';
-  /** 协议端实现的 Milky 协议版本，目前为 "1.2" */
+  /** 协议端实现的 Milky 协议版本，目前为 "1.3" */
   milky_version: string;
 }
 /** 获取协议端信息 API 响应数据 */
@@ -2868,7 +2868,7 @@ interface GetImplInfoOutput_ZodInput {
     | 'iphone'
     | 'harmony'
     | 'watch';
-  /** 协议端实现的 Milky 协议版本，目前为 "1.2" */
+  /** 协议端实现的 Milky 协议版本，目前为 "1.3" */
   milky_version: string;
 }
 /** 获取用户个人信息 API 请求参数 */
@@ -4151,6 +4151,8 @@ interface GetPrivateFileDownloadUrlInput {
   file_id: string;
   /** 文件的 TriSHA1 哈希值 */
   file_hash: string;
+  /** 是否为自己发送的文件 */
+  is_self_send: boolean;
 }
 /** 获取私聊文件下载链接 API 请求参数 */
 interface GetPrivateFileDownloadUrlInput_ZodInput {
@@ -4160,6 +4162,8 @@ interface GetPrivateFileDownloadUrlInput_ZodInput {
   file_id: string;
   /** 文件的 TriSHA1 哈希值 */
   file_hash: string;
+  /** 是否为自己发送的文件 */
+  is_self_send?: boolean | null | undefined;
 }
 /** 获取私聊文件下载链接 API 响应数据 */
 interface GetPrivateFileDownloadUrlOutput {
@@ -5373,52 +5377,6 @@ interface ApiEndpoints$1 {
   };
 }
 //#endregion
-//#region src/protocol/endpoint.d.ts
-type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
-type AllOptional<T> = RequiredKeys<T> extends never ? true : false;
-type RawApiEndpoint<E extends keyof ApiEndpoints$1> = {
-  request: ApiEndpoints$1[E]['request_ZodInput'] extends null ? null : ApiEndpoints$1[E]['request_ZodInput'];
-  response: ApiEndpoints$1[E]['response'] extends null ? null : ApiEndpoints$1[E]['response'];
-};
-type ApiEndpointFunction<E extends keyof ApiEndpoints$1> = RawApiEndpoint<E>['request'] extends null
-  ? () => Promise<RawApiEndpoint<E>['response']>
-  : AllOptional<RawApiEndpoint<E>['request']> extends true
-    ? (params?: RawApiEndpoint<E>['request']) => Promise<RawApiEndpoint<E>['response']>
-    : (params: RawApiEndpoint<E>['request']) => Promise<RawApiEndpoint<E>['response']>;
-type ApiEndpoints = { [E in keyof ApiEndpoints$1]: ApiEndpointFunction<E> };
-type EventMap = {
-  [K in Event['event_type']]: Extract<
-    Event,
-    {
-      event_type: K;
-    }
-  >;
-};
-//#endregion
-//#region src/protocol/client.d.ts
-interface MilkyEventSubscription {
-  closed: Promise<void>;
-  stop(): void | Promise<void>;
-}
-interface MilkyClient extends ApiEndpoints {
-  startEvents(onEvent: (event: Event) => void | Promise<void>): Promise<MilkyEventSubscription>;
-}
-declare class MilkyClientBase {
-  readonly baseUrl: string;
-  readonly wsBaseUrl: string;
-  private readonly accessToken?;
-  private readonly baseHeaders;
-  constructor(
-    baseUrl: string | URL,
-    options?: {
-      accessToken?: string;
-    },
-  );
-  callApi(endpoint: string, params?: unknown): Promise<unknown>;
-  startEvents(onEvent: (event: Event) => void | Promise<void>): Promise<MilkyEventSubscription>;
-}
-declare function createMilkyClient(...params: ConstructorParameters<typeof MilkyClientBase>): MilkyClient;
-//#endregion
 //#region src/routing/tokenizer.d.ts
 type Token =
   | string
@@ -5446,6 +5404,8 @@ declare class Tokenizer {
   greedy(): string;
   isCatchAllAvailable(): boolean;
   catchAll(): IncomingSegment[];
+  consumeMention(userId: number): boolean;
+  consumeTextPrefix(prefix: string): boolean;
   private findNextPosition;
   private findTextTokenStart;
   private readTextToken;
@@ -5512,6 +5472,9 @@ declare namespace param {
 type Pattern = Record<string, Parameter<any>>;
 type ParamsOf<P extends Pattern> = { [K in keyof P]: P[K] extends Parameter<infer T> ? T : never };
 type Executor<P extends Pattern> = (session: Session, params: ParamsOf<P>) => void | Promise<void>;
+type RouteMeta = Record<string, unknown> & {
+  tags?: readonly string[];
+};
 interface Command<P extends Pattern> {
   name: string;
   pattern: P;
@@ -5519,16 +5482,19 @@ interface Command<P extends Pattern> {
   description?: string;
   aliases?: string[];
   hidden?: boolean;
+  meta?: RouteMeta;
 }
 interface RawPattern<P extends Pattern> {
   pattern: P;
   execute: Executor<P>;
+  meta?: RouteMeta;
 }
 interface SessionReplyOptions {
   withQuote?: boolean;
   withMention?: boolean;
 }
 interface Session {
+  selfId: number;
   raw: IncomingMessage;
   reply(
     textOrSegments: string | OutgoingSegment_ZodInput[],
@@ -5546,6 +5512,7 @@ declare class CommandBuilder<P extends Pattern = {}, S = Command<P>> {
   private description?;
   private aliases?;
   private hidden?;
+  private routeMeta?;
   constructor(name: string, sink?: (command: Command<P>) => S);
   arg<K extends string, T>(
     key: K,
@@ -5561,11 +5528,40 @@ declare class CommandBuilder<P extends Pattern = {}, S = Command<P>> {
   describe(description: string): CommandBuilder<P, S>;
   alias(...aliases: string[]): CommandBuilder<P, S>;
   hide(): CommandBuilder<P, S>;
+  meta(meta: RouteMeta): CommandBuilder<P, S>;
+  tag(...tags: string[]): CommandBuilder<P, S>;
   execute(executor: Executor<P>): S;
 }
+declare function mergeRouteMeta(left?: RouteMeta, right?: RouteMeta): RouteMeta | undefined;
 //#endregion
 //#region src/routing/router.d.ts
 type SessionPredicate = (session: Session) => boolean;
+type RouteActivation =
+  | {
+      type: 'direct';
+    }
+  | {
+      type: 'mention';
+    }
+  | {
+      type: 'prefix';
+      prefix: string;
+    };
+type RouteDescriptor =
+  | {
+      type: 'command';
+      path: readonly string[];
+      name: string;
+      aliases?: readonly string[];
+      meta?: RouteMeta;
+    }
+  | {
+      type: 'rawPattern';
+      path: readonly string[];
+      meta?: RouteMeta;
+    };
+type RouteActivationResolver = (route: RouteDescriptor, session: Session) => readonly RouteActivation[] | undefined;
+declare const defaultRouteActivationResolver: RouteActivationResolver;
 type RouteEntry =
   | {
       type: 'command';
@@ -5590,11 +5586,13 @@ type RouteBranch =
       type: 'command';
       path: string[];
       command: Command<Pattern>;
+      meta?: RouteMeta;
     }
   | {
       type: 'rawPattern';
       path: string[];
       rawPattern: RawPattern<Pattern>;
+      meta?: RouteMeta;
     };
 type RouteMatchResult =
   | {
@@ -5602,16 +5600,22 @@ type RouteMatchResult =
       path: string[];
       command: Command<Pattern>;
       params: any;
+      activation?: RouteActivation;
     }
   | {
       type: 'rawPattern';
       path: string[];
       rawPattern: RawPattern<Pattern>;
       params: any;
+      activation?: RouteActivation;
     };
 declare class Router {
-  private readonly entries;
-  private readonly groups;
+  private entries;
+  private groups;
+  private activationResolver;
+  private scopeMeta?;
+  setActivationResolver(resolver: RouteActivationResolver): this;
+  withMeta(meta: RouteMeta): Router;
   command(name: string): CommandBuilder;
   command<P extends Pattern>(command: Command<P>): this;
   rawPattern(): CommandBuilder<{}, RawPattern<{}>>;
@@ -5623,17 +5627,107 @@ declare class Router {
   branches(session: Session): RouteBranch[];
   match(session: Session, message: IncomingMessage): RouteMatchResult | undefined;
   dispatch(session: Session, message: IncomingMessage): Promise<boolean>;
-  private matchFrom;
-  private matchEntry;
+  private describeBranch;
+  private consumeActivation;
+  private matchBranch;
+  private matchPath;
   private matchCommand;
-  private matchGroup;
   private matchRawPattern;
   private branchesFrom;
+  private applyScopeMeta;
   private resolveAliasConflicts;
   private validatePattern;
   private capturePattern;
 }
 //#endregion
+//#region src/core/activation.d.ts
+type ContextRouteActivationByScene = Partial<
+  Record<IncomingMessage['message_scene'] | 'default', readonly RouteActivation[]>
+>;
+type ContextRouteActivation = readonly RouteActivation[] | ContextRouteActivationByScene;
+interface ContextRouteActivationMatcher {
+  type?: RouteDescriptor['type'] | readonly RouteDescriptor['type'][];
+  plugin?: string | readonly string[];
+  context?: string | readonly string[];
+  tag?: string | readonly string[];
+  command?: string | readonly string[];
+  path?: readonly string[];
+  route?: readonly string[];
+  predicate?: (route: RouteDescriptor, session: Session) => boolean;
+}
+interface ContextRouteActivationRule {
+  match?: ContextRouteActivationMatcher;
+  activation: ContextRouteActivation;
+}
+interface ContextRouteActivationConfig {
+  default?: ContextRouteActivation;
+  rules?: ContextRouteActivationRule | readonly ContextRouteActivationRule[];
+}
+interface ContextRoutingOptions {
+  activation?: ContextRouteActivationConfig;
+  activationResolver?: RouteActivationResolver;
+}
+declare function createContextRouteActivationResolver(
+  routing: ContextRoutingOptions | undefined,
+  fallback?: RouteActivationResolver,
+): RouteActivationResolver;
+//#endregion
+//#region src/protocol/endpoint.d.ts
+type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
+type AllOptional<T> = RequiredKeys<T> extends never ? true : false;
+type RawApiEndpoint<E extends keyof ApiEndpoints$1> = {
+  request: ApiEndpoints$1[E]['request_ZodInput'] extends null ? null : ApiEndpoints$1[E]['request_ZodInput'];
+  response: ApiEndpoints$1[E]['response'] extends null ? null : ApiEndpoints$1[E]['response'];
+};
+type ApiEndpointFunction<E extends keyof ApiEndpoints$1> = RawApiEndpoint<E>['request'] extends null
+  ? () => Promise<RawApiEndpoint<E>['response']>
+  : AllOptional<RawApiEndpoint<E>['request']> extends true
+    ? (params?: RawApiEndpoint<E>['request']) => Promise<RawApiEndpoint<E>['response']>
+    : (params: RawApiEndpoint<E>['request']) => Promise<RawApiEndpoint<E>['response']>;
+type ApiEndpoints = { [E in keyof ApiEndpoints$1]: ApiEndpointFunction<E> };
+type EventMap = {
+  [K in Event['event_type']]: Extract<
+    Event,
+    {
+      event_type: K;
+    }
+  >;
+};
+//#endregion
+//#region src/protocol/client.d.ts
+interface MilkyClient extends ApiEndpoints {}
+declare class MilkyClientBase {
+  readonly baseUrl: string;
+  readonly wsBaseUrl: string;
+  private readonly accessToken?;
+  private readonly baseHeaders;
+  constructor(
+    baseUrl: string | URL,
+    options?: {
+      accessToken?: string;
+    },
+  );
+  callApi(endpoint: string, params?: unknown): Promise<unknown>;
+}
+declare function createMilkyClient(...params: ConstructorParameters<typeof MilkyClientBase>): MilkyClient;
+//#endregion
+//#region src/protocol/event.d.ts
+interface MilkyEventSubscription {
+  closed: Promise<void>;
+  stop(): void | Promise<void>;
+}
+interface MilkyEventSource {
+  readonly name?: string;
+  start(onEvent: (event: Event) => void | Promise<void>): Promise<MilkyEventSubscription>;
+}
+interface MilkyWebSocketEventSourceOptions {
+  accessToken?: string;
+}
+declare function createMilkyWebSocketEventSource(
+  baseUrl: string | URL,
+  options?: MilkyWebSocketEventSourceOptions,
+): MilkyEventSource;
+//#endregion
 //#region src/core/filter.d.ts
 type Filter = { [K in keyof EventMap]?: (event: EventMap[K]) => boolean };
 declare namespace filter {
@@ -5716,21 +5810,25 @@ interface ContextOptions {
     maxDelayMs?: number;
   };
   logHandler?: LogHandler;
+  routing?: ContextRoutingOptions;
 }
 interface ContextUrlOptions {
   accessToken?: string;
+  installEventSource?: boolean;
 }
 declare class Context {
   readonly client: MilkyClient;
   readonly router: Router;
   readonly logger: Logger;
   readonly name: string;
+  readonly routeActivationResolver: RouteActivationResolver;
   private readonly parent?;
   private readonly filter?;
   private readonly eventBus;
   private readonly plugins;
   private readonly services;
   private readonly subContexts;
+  private readonly eventSourceRuntimes;
   private readonly parentEventForwarder?;
   private readonly timers;
   private readonly initialReconnectDelayMs;
@@ -5739,16 +5837,13 @@ declare class Context {
   private state;
   private startPromise?;
   private stopPromise?;
-  private eventSubscription?;
-  private eventStreamTask?;
-  private reconnectTimer?;
-  private resolveReconnectTimer?;
   private constructor();
   on<K extends keyof EventMap>(type: K, handler: (event: EventMap[K]) => void | Promise<void>): () => void;
   install<T extends ParameterList, I extends Injection | undefined, OI extends Injection | undefined>(
     plugin: Plugin<T, I, OI>,
     ...args: T
   ): void;
+  installEventSource(eventSource: MilkyEventSource): void;
   provide<T extends object>(service: ServiceClass<T>, instance: T): void;
   resolve<T extends object>(service: ServiceClass<T>): T;
   tryResolve<T extends object>(service: ServiceClass<T>): T | undefined;
@@ -5756,7 +5851,7 @@ declare class Context {
   fork(name: string, filter?: Filter): Context;
   timeout(delayMs: number, callback: () => void | Promise<void>): NodeJS.Timeout;
   interval(intervalMs: number, callback: () => void | Promise<void>): NodeJS.Timeout;
-  createSession(message: IncomingMessage): Session;
+  createSession(selfId: number, message: IncomingMessage): Session;
   start(): Promise<void>;
   stop(): Promise<void>;
   private startInternal;
@@ -5765,7 +5860,7 @@ declare class Context {
   private assertCanScheduleTimer;
   private runTimerCallback;
   private clearTimers;
-  private stopEventStream;
+  private stopEventSources;
   private acceptsParentEvent;
   private applyPlugins;
   private recursiveApplyPlugins;
@@ -5779,7 +5874,8 @@ declare class Context {
   private createUnresolvablePluginError;
   private getPluginContext;
   private createProxyContextForPlugin;
-  private runEventStream;
+  private startEventSource;
+  private runEventSource;
   private waitForReconnectDelay;
   private resolveReconnectDelay;
   static fromUrl(baseUrl: string | URL, options?: ContextOptions & ContextUrlOptions): Context;
@@ -5833,6 +5929,12 @@ export {
   CommandBuilder,
   Context,
   ContextOptions,
+  ContextRouteActivation,
+  ContextRouteActivationByScene,
+  ContextRouteActivationConfig,
+  ContextRouteActivationMatcher,
+  ContextRouteActivationRule,
+  ContextRoutingOptions,
   ContextUrlOptions,
   Disposable,
   EventMap,
@@ -5844,16 +5946,22 @@ export {
   LogMessage,
   Logger,
   MilkyClient,
+  MilkyEventSource,
   MilkyEventSubscription,
+  MilkyWebSocketEventSourceOptions,
   Parameter,
   ParameterList,
   ParamsOf,
   Pattern,
   Plugin,
   RawPattern,
+  RouteActivation,
+  RouteActivationResolver,
   RouteBranch,
+  RouteDescriptor,
   RouteEntry,
   RouteMatchResult,
+  RouteMeta,
   Router,
   ServiceClass,
   Session,
@@ -5861,11 +5969,15 @@ export {
   SessionReplyOptions,
   TypeInstruction,
   combineLogHandlers,
+  createContextRouteActivationResolver,
   createMilkyClient,
+  createMilkyWebSocketEventSource,
+  defaultRouteActivationResolver,
   definePlugin,
   filter,
   implementsESNextDisposable,
   isDisposable,
+  mergeRouteMeta,
   type types_d_exports as milky,
   milkyPackageVersion,
   milkyVersion,