@fraqjs/fraq 0.12.0 → 0.13.0

package/dist/index.d.mts

@@ -5547,6 +5547,7 @@ type RouteActivation =
       type: 'prefix';
       prefix: string;
     };
+type RouteActivationInput = RouteActivation | readonly RouteActivation[];
 type RouteDescriptor =
   | {
       type: 'command';
@@ -5560,7 +5561,7 @@ type RouteDescriptor =
       path: readonly string[];
       meta?: RouteMeta;
     };
-type RouteActivationResolver = (route: RouteDescriptor, session: Session) => readonly RouteActivation[] | undefined;
+type RouteActivationResolver = (route: RouteDescriptor, session: Session) => RouteActivationInput | undefined;
 declare const defaultRouteActivationResolver: RouteActivationResolver;
 type RouteEntry =
   | {
@@ -5642,9 +5643,9 @@ declare class Router {
 //#endregion
 //#region src/core/activation.d.ts
 type ContextRouteActivationByScene = Partial<
-  Record<IncomingMessage['message_scene'] | 'default', readonly RouteActivation[]>
+  Record<IncomingMessage['message_scene'] | 'default', RouteActivationInput>
 >;
-type ContextRouteActivation = readonly RouteActivation[] | ContextRouteActivationByScene;
+type ContextRouteActivation = RouteActivationInput | ContextRouteActivationByScene;
 interface ContextRouteActivationMatcher {
   type?: RouteDescriptor['type'] | readonly RouteDescriptor['type'][];
   plugin?: string | readonly string[];
@@ -5673,18 +5674,42 @@ declare function createContextRouteActivationResolver(
 ): RouteActivationResolver;
 //#endregion
 //#region src/protocol/endpoint.d.ts
+type ApiEndpointName = keyof ApiEndpoints$1;
 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> = {
+type RawApiEndpoint<E extends ApiEndpointName> = {
   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']>
+type ApiRequest<E extends ApiEndpointName> = RawApiEndpoint<E>['request'];
+type ApiParams<E extends ApiEndpointName> = RawApiEndpoint<E>['request'] extends null
+  ? undefined
   : 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> };
+    ? RawApiEndpoint<E>['request'] | undefined
+    : RawApiEndpoint<E>['request'];
+type ApiResponse<E extends ApiEndpointName> = RawApiEndpoint<E>['response'];
+interface ApiCall<E extends ApiEndpointName = ApiEndpointName> {
+  endpoint: E;
+  params: ApiParams<E>;
+}
+type ApiNext<E extends ApiEndpointName> =
+  undefined extends ApiParams<E>
+    ? (params?: ApiParams<E>) => Promise<ApiResponse<E>>
+    : (params: ApiParams<E>) => Promise<ApiResponse<E>>;
+type ApiHook<E extends ApiEndpointName> = (
+  params: ApiParams<E>,
+  next: ApiNext<E>,
+  call: ApiCall<E>,
+) => ApiResponse<E> | Promise<ApiResponse<E>>;
+type AnyApiCall = { [E in ApiEndpointName]: ApiCall<E> }[ApiEndpointName];
+type AnyApiNext = (params?: unknown) => Promise<unknown>;
+type AnyApiHook = (call: AnyApiCall, next: AnyApiNext) => unknown | Promise<unknown>;
+type ApiEndpointFunction<E extends ApiEndpointName> = RawApiEndpoint<E>['request'] extends null
+  ? () => Promise<ApiResponse<E>>
+  : AllOptional<RawApiEndpoint<E>['request']> extends true
+    ? (params?: RawApiEndpoint<E>['request']) => Promise<ApiResponse<E>>
+    : (params: RawApiEndpoint<E>['request']) => Promise<ApiResponse<E>>;
+type ApiEndpoints = { [E in ApiEndpointName]: ApiEndpointFunction<E> };
 type EventMap = {
   [K in Event['event_type']]: Extract<
     Event,
@@ -5817,16 +5842,18 @@ interface ContextUrlOptions {
   installEventSource?: boolean;
 }
 declare class Context {
-  readonly client: MilkyClient;
   readonly router: Router;
   readonly logger: Logger;
   readonly name: string;
   readonly routeActivationResolver: RouteActivationResolver;
+  readonly client: MilkyClient;
+  private readonly baseClient;
   private readonly parent?;
   private readonly filter?;
   private readonly eventBus;
   private readonly plugins;
   private readonly services;
+  private readonly apiHookEntries;
   private readonly subContexts;
   private readonly eventSourceRuntimes;
   private readonly parentEventForwarder?;
@@ -5844,6 +5871,8 @@ declare class Context {
     ...args: T
   ): void;
   installEventSource(eventSource: MilkyEventSource): void;
+  hookApi<E extends ApiEndpointName>(endpoint: E, hook: ApiHook<E>): () => void;
+  hookApi(hook: AnyApiHook): () => 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;
@@ -5857,6 +5886,7 @@ declare class Context {
   private startInternal;
   private getState;
   private stopInternal;
+  private assertCanRegisterApiHook;
   private assertCanScheduleTimer;
   private runTimerCallback;
   private clearTimers;
@@ -5878,6 +5908,11 @@ declare class Context {
   private runEventSource;
   private waitForReconnectDelay;
   private resolveReconnectDelay;
+  private createHookClient;
+  private wrapAnyApiHook;
+  private callHookedApi;
+  private collectApiHooks;
+  private callBaseApi;
   static fromUrl(baseUrl: string | URL, options?: ContextOptions & ContextUrlOptions): Context;
   static fromClient(client: MilkyClient, options?: ContextOptions): Context;
 }
@@ -5923,7 +5958,17 @@ declare namespace seg {
 }
 //#endregion
 export {
+  AnyApiCall,
+  AnyApiHook,
+  AnyApiNext,
+  ApiCall,
+  ApiEndpointName,
   ApiEndpoints,
+  ApiHook,
+  ApiNext,
+  ApiParams,
+  ApiRequest,
+  ApiResponse,
   Capturer,
   Command,
   CommandBuilder,
@@ -5956,6 +6001,7 @@ export {
   Plugin,
   RawPattern,
   RouteActivation,
+  RouteActivationInput,
   RouteActivationResolver,
   RouteBranch,
   RouteDescriptor,

package/dist/index.mjs

@@ -75,7 +75,7 @@ function uniqueTags(...tagLists) {
 }
 //#endregion
 //#region src/routing/tokenizer.ts
-const WHITESPACE_CHARS = new Set([
+const WHITESPACE_CHARS = /* @__PURE__ */ new Set([
 	" ",
 	"	",
 	"\n",
@@ -316,7 +316,7 @@ var Router = class Router {
 		for (const branch of this.branchesFrom(session, [], { includeHidden: true })) {
 			const descriptor = this.describeBranch(branch);
 			const activations = this.activationResolver(descriptor, session) ?? DEFAULT_ACTIVATIONS;
-			for (const activation of activations) {
+			for (const activation of routeActivationInputs(activations)) {
 				const tokenizer = new Tokenizer(message.segments);
 				if (!this.consumeActivation(tokenizer, activation, session)) continue;
 				const match = this.matchBranch(branch, tokenizer, activation);
@@ -485,6 +485,12 @@ var Router = class Router {
 		return params;
 	}
 };
+function routeActivationInputs(activations) {
+	return isRouteActivationArray(activations) ? activations : [activations];
+}
+function isRouteActivationArray(activations) {
+	return Array.isArray(activations);
+}
 //#endregion
 //#region src/core/activation.ts
 function createContextRouteActivationResolver(routing, fallback = defaultRouteActivationResolver) {
@@ -516,11 +522,14 @@ function isContextRouteActivationRuleArray(rules) {
 	return Array.isArray(rules);
 }
 function resolveContextRouteActivation(activation, scene) {
-	if (isRouteActivationArray(activation)) return activation;
+	if (isRouteActivationInput(activation)) return activation;
 	return activation[scene] ?? activation.default;
 }
-function isRouteActivationArray(activation) {
-	return Array.isArray(activation);
+function isRouteActivationInput(activation) {
+	return Array.isArray(activation) || isRouteActivation(activation);
+}
+function isRouteActivation(activation) {
+	return "type" in activation;
 }
 function matchesContextRouteActivationRule(route, session, rule) {
 	const match = rule.match;
@@ -811,16 +820,18 @@ function implementsESNextDisposable(service) {
 const DEFAULT_INITIAL_RECONNECT_DELAY_MS = 1e3;
 const DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
 var Context = class Context {
-	client;
 	router = new Router();
 	logger;
 	name;
 	routeActivationResolver;
+	client;
+	baseClient;
 	parent;
 	filter;
 	eventBus = mitt();
 	plugins = [];
 	services = /* @__PURE__ */ new Map();
+	apiHookEntries = [];
 	subContexts = /* @__PURE__ */ new Map();
 	eventSourceRuntimes = /* @__PURE__ */ new Map();
 	parentEventForwarder;
@@ -831,8 +842,9 @@ var Context = class Context {
 	state = "idle";
 	startPromise;
 	stopPromise;
-	constructor(client, options, name, parent, filter) {
-		this.client = client;
+	constructor(baseClient, options, name, parent, filter) {
+		this.baseClient = baseClient;
+		this.client = this.createHookClient();
 		this.initialReconnectDelayMs = options?.reconnect?.initialDelayMs ?? DEFAULT_INITIAL_RECONNECT_DELAY_MS;
 		this.maxReconnectDelayMs = options?.reconnect?.maxDelayMs ?? DEFAULT_MAX_RECONNECT_DELAY_MS;
 		this.logHandler = options?.logHandler ?? parent?.logHandler;
@@ -883,6 +895,26 @@ var Context = class Context {
 		this.eventSourceRuntimes.set(eventSource, {});
 		if (this.state === "started") this.startEventSource(eventSource);
 	}
+	hookApi(endpointOrHook, hook) {
+		this.assertCanRegisterApiHook();
+		let entry;
+		if (typeof endpointOrHook === "function") entry = { hook: this.wrapAnyApiHook(endpointOrHook) };
+		else {
+			if (!hook) throw new Error(`API hook for endpoint ${endpointOrHook} is missing a handler.`);
+			entry = {
+				endpoint: endpointOrHook,
+				hook
+			};
+		}
+		this.apiHookEntries.push(entry);
+		let disposed = false;
+		return () => {
+			if (disposed) return;
+			disposed = true;
+			const index = this.apiHookEntries.indexOf(entry);
+			if (index !== -1) this.apiHookEntries.splice(index, 1);
+		};
+	}
 	provide(service, instance) {
 		if (this.services.has(service)) throw new Error(`Service ${service.name} has already been provided in this context.`);
 		if (implementsESNextDisposable(instance) && !isDisposable(instance)) throw new Error(`
@@ -912,7 +944,7 @@ and implement the dispose method to clean up resources when the context stops.
 			if (filter) throw new Error(`Sub context "${name}" already exists, so the provided filter cannot be applied. Please use fork('${name}') without a filter to get the existing subcontext.`);
 			return this.subContexts.get(name);
 		}
-		const subContext = new Context(this.client, void 0, name, this, filter);
+		const subContext = new Context(this.baseClient, void 0, name, this, filter);
 		this.subContexts.set(name, subContext);
 		return subContext;
 	}
@@ -1044,9 +1076,14 @@ and implement the dispose method to clean up resources when the context stops.
 				errors.push(error);
 			}
 		}
+		this.apiHookEntries.length = 0;
 		if (errors.length === 1) throw errors[0];
 		if (errors.length > 1) throw new AggregateError(errors, `Context "${this.name}" failed to stop cleanly.`);
 	}
+	assertCanRegisterApiHook() {
+		if (this.state === "stopping") throw new Error(`Context "${this.name}" cannot register API hooks while it is stopping.`);
+		if (this.state === "stopped") throw new Error(`Context "${this.name}" cannot register API hooks after it has stopped.`);
+	}
 	assertCanScheduleTimer() {
 		if (this.state === "stopping") throw new Error(`Context "${this.name}" cannot schedule timers while it is stopping.`);
 		if (this.state === "stopped") throw new Error(`Context "${this.name}" cannot schedule timers after it has stopped.`);
@@ -1281,8 +1318,53 @@ and implement the dispose method to clean up resources when the context stops.
 		runtime.resolveReconnectTimer = void 0;
 		resolve?.();
 	}
+	createHookClient() {
+		return new Proxy(this.baseClient, { get: (target, prop, receiver) => {
+			if (typeof prop === "string" && prop.includes("_")) return (params) => this.callHookedApi(prop, params);
+			return Reflect.get(target, prop, receiver);
+		} });
+	}
+	wrapAnyApiHook(hook) {
+		return (params, next, call) => {
+			return hook(call, (nextParams = params) => next(nextParams));
+		};
+	}
+	async callHookedApi(endpoint, params) {
+		const hooks = this.collectApiHooks(endpoint);
+		const dispatch = async (index, currentParams) => {
+			const hook = hooks[index];
+			if (!hook) return await this.callBaseApi(endpoint, currentParams);
+			let nextCalled = false;
+			return await hook(currentParams, async (nextParams = currentParams) => {
+				if (nextCalled) throw new Error(`API hook for endpoint ${endpoint} called next() multiple times.`);
+				nextCalled = true;
+				return await dispatch(index + 1, nextParams);
+			}, {
+				endpoint,
+				params: currentParams
+			});
+		};
+		return await dispatch(0, params);
+	}
+	collectApiHooks(endpoint) {
+		const hooks = [];
+		let context = this;
+		while (context) {
+			for (const entry of context.apiHookEntries.toReversed()) if (entry.endpoint === void 0 || entry.endpoint === endpoint) hooks.push(entry.hook);
+			context = context.parent;
+		}
+		return hooks;
+	}
+	async callBaseApi(endpoint, params) {
+		const callApi = this.baseClient.callApi;
+		if (typeof callApi === "function") return await callApi.call(this.baseClient, endpoint, params);
+		const method = this.baseClient[endpoint];
+		if (typeof method !== "function") throw new Error(`Milky client does not implement API endpoint ${endpoint}.`);
+		return await method.call(this.baseClient, params);
+	}
 	static fromUrl(baseUrl, options) {
-		const context = new Context(createMilkyClient(baseUrl, { accessToken: options?.accessToken }), options);
+		const client = createMilkyClient(baseUrl, { accessToken: options?.accessToken });
+		const context = new Context(client, options);
 		if (options?.installEventSource ?? true) context.installEventSource(createMilkyWebSocketEventSource(baseUrl, { accessToken: options?.accessToken }));
 		return context;
 	}

package/package.json

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