@zhin.js/middleware 1.1.12 → 1.1.14

package/lib/definition.d.ts

@@ -10,11 +10,19 @@ export type MiddlewarePhase = 'before-dispatch' | 'after-dispatch';
 export type MiddlewareTarget = 'inbound' | 'outbound';
 export type MiddlewareNext = () => Promise<MiddlewareContinuation>;
 export type OutboundMiddlewareNext = () => Promise<void>;
+export interface InboundDispatchSummary {
+    readonly matched: boolean;
+    readonly path: 'button' | 'command' | 'handler' | 'none';
+    readonly handlerId?: string;
+    readonly replied: boolean;
+}
 export interface MiddlewareContext<TInput = unknown, TConfig = unknown, TAdapter extends string | undefined = undefined> extends CapabilityContext<TConfig> {
     readonly input: TInput;
     /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
     readonly $client: AdapterClient<TAdapter>;
     readonly session: OperationSession<TAdapter> | undefined;
+    readonly dispatch?: InboundDispatchSummary;
+    onAfterDispatch?(listener: (summary: InboundDispatchSummary) => void | Promise<void>): void;
 }
 /** Shared metadata for the public inbound and outbound definition contracts. */
 export interface MiddlewareDefinitionBase<TAdapter extends string | undefined = string | undefined> {
@@ -46,16 +54,17 @@ declare module '@zhin.js/plugin-runtime' {
  */
 type AuthoringForAdapter<TInput, TConfig, TAdapter extends string | undefined> = Omit<MiddlewareDefinitionBase<TAdapter>, '$feature' | 'phase' | 'order'> & {
     readonly phase?: MiddlewarePhase;
+    readonly stage?: MiddlewarePhase;
     readonly order?: number;
 } & ({
     readonly target?: 'inbound';
-    handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: MiddlewareNext): unknown;
+    handle(this: MiddlewareContext<TInput, TConfig, TAdapter>, context: MiddlewareContext<TInput, TConfig, TAdapter>, next: MiddlewareNext): unknown;
 } | {
     readonly target: 'outbound';
     /** Opt in to cumulative prefixes. Previously published text, format and addressing must stay stable;
      * do not repeat approvals, external sends or other side effects. */
     readonly incremental?: true;
-    handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: OutboundMiddlewareNext): void | Promise<void>;
+    handle(this: MiddlewareContext<TInput, TConfig, TAdapter>, context: MiddlewareContext<TInput, TConfig, TAdapter>, next: OutboundMiddlewareNext): void | Promise<void>;
 });
 /** @internal Shape shared with the typed IM facade; not a separate authoring API. */
 export type MiddlewareAuthoringDefinition<TInput, TConfig> = AuthoringForAdapter<TInput, TConfig, undefined> | {
@@ -63,6 +72,24 @@ export type MiddlewareAuthoringDefinition<TInput, TConfig> = AuthoringForAdapter
         readonly adapter: TAdapter;
     };
 }[RegisteredAdapterName];
+/**
+ * Returned by `defineMiddleware.withConfig<Config>()`: fixes the plugin config type while
+ * keeping inbound/outbound input inference intact.
+ *
+ * @public
+ */
+export interface MiddlewareDefiner<TConfig> {
+    <TInput = unknown>(definition: Extract<MiddlewareAuthoringDefinition<TInput, TConfig>, {
+        readonly target: 'outbound';
+    }>): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, {
+        readonly target: 'outbound';
+    }>>;
+    <TInput = unknown>(definition: Extract<MiddlewareAuthoringDefinition<TInput, TConfig>, {
+        readonly target?: 'inbound';
+    }>): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, {
+        readonly target: 'inbound';
+    }>>;
+}
 export declare function defineMiddleware<TInput = unknown, TConfig = unknown>(definition: Extract<MiddlewareAuthoringDefinition<TInput, TConfig>, {
     readonly target: 'outbound';
 }>): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, {
@@ -73,5 +100,8 @@ export declare function defineMiddleware<TInput = unknown, TConfig = unknown>(de
 }>): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, {
     readonly target: 'inbound';
 }>>;
+export declare namespace defineMiddleware {
+    var withConfig: <TConfig = unknown>() => MiddlewareDefiner<TConfig>;
+}
 /** @internal Runtime validation for convention-discovered modules. */
 export declare function parseMiddlewareDefinition(value: unknown): MiddlewareDefinition;

package/lib/definition.js

@@ -8,7 +8,7 @@ export function defineMiddleware(definition) {
         && (typeof adapter !== 'string' || adapter.trim() === '')) {
         throw new TypeError('Middleware adapter must be a non-empty string');
     }
-    const phase = definition.phase ?? 'before-dispatch';
+    const phase = definition.phase ?? definition.stage ?? 'before-dispatch';
     if (phase !== 'before-dispatch' && phase !== 'after-dispatch') {
         throw new TypeError(`Invalid Middleware phase: ${String(phase)}`);
     }
@@ -21,6 +21,12 @@ export function defineMiddleware(definition) {
         throw new TypeError('Middleware order must be a safe integer');
     return Object.freeze({ ...definition, $feature: middlewareBrand, phase, target, order });
 }
+/**
+ * Fix the plugin config type first, then define the middleware.
+ */
+defineMiddleware.withConfig = function withConfig() {
+    return ((definition) => defineMiddleware(definition));
+};
 /** @internal Runtime validation for convention-discovered modules. */
 export function parseMiddlewareDefinition(value) {
     if (!value || typeof value !== 'object')

package/lib/middleware-index.d.ts

@@ -1,9 +1,14 @@
 import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import type { MiddlewareDefinition, MiddlewarePhase, MiddlewareTarget, OutboundMiddlewareNext } from './definition.js';
+import type { InboundDispatchSummary, MiddlewareDefinition, MiddlewarePhase, MiddlewareTarget, OutboundMiddlewareNext } from './definition.js';
+/** @internal Terminal control passed to inbound terminal callbacks to publish dispatch summary before after-dispatch unwinds. */
+export interface InboundTerminalControl {
+    reportDispatch(summary: InboundDispatchSummary): Promise<void>;
+}
 /** @internal Transmission-neutral result policy supplied by the composition layer. */
 export interface MiddlewareResultPolicy<TResult> {
     stop(owner: PluginId): TResult;
     replace(owner: PluginId, value: unknown, downstream: TResult | undefined): TResult;
+    summarize?(result: TResult): InboundDispatchSummary | undefined;
 }
 /** @internal Runtime continuation result. */
 export interface MiddlewareRunResult {
@@ -32,7 +37,7 @@ export declare class MiddlewareIndex {
     run<TInput>(input: TInput, terminal: OutboundMiddlewareNext | undefined, target: 'outbound', operationSnapshot?: RuntimeSnapshot): Promise<void>;
     run<TInput>(input: TInput, terminal: OutboundMiddlewareNext | undefined, target: MiddlewareTarget, operationSnapshot?: RuntimeSnapshot): Promise<MiddlewareRunResult | void>;
     /** Unwinds one inbound operation before its caller performs any automatic reply. */
-    runInbound<TInput, TResult>(input: TInput, terminal: () => Promise<TResult>, results: MiddlewareResultPolicy<TResult>, operationSnapshot?: RuntimeSnapshot): Promise<TResult>;
+    runInbound<TInput, TResult>(input: TInput, terminal: (control: InboundTerminalControl) => Promise<TResult>, results: MiddlewareResultPolicy<TResult>, operationSnapshot?: RuntimeSnapshot): Promise<TResult>;
 }
 /** @internal Runtime projection guard. */
 export declare function isMiddlewareIndex(value: unknown): value is MiddlewareIndex;

package/lib/middleware-index.js

@@ -42,7 +42,7 @@ export class MiddlewareIndex {
                 return terminal();
             const authorInput = bindOperationInput(input, record.owner, operationSnapshot);
             const context = {
-                ...createCapabilityContext(operationSnapshot, record.owner, undefined, readOperationSession(authorInput, record.adapter)?.signal),
+                ...createCapabilityContext({ snapshot: operationSnapshot, ownerId: record.owner, admission: undefined, signal: readOperationSession(authorInput, record.adapter)?.signal }),
                 input: authorInput,
             };
             Object.defineProperty(context, 'session', {
@@ -56,7 +56,7 @@ export class MiddlewareIndex {
             const definition = record.slot.definition;
             if (definition.target !== 'outbound')
                 throw new Error('Invalid outbound Middleware');
-            const result = await definition.handle(context, () => dispatch(index + 1));
+            const result = await definition.handle.call(context, context, () => dispatch(index + 1));
             if (result !== undefined)
                 throw new TypeError('Outbound Middleware must use input.replace(), not return content');
         };
@@ -67,16 +67,41 @@ export class MiddlewareIndex {
         const clientAdapter = operationClientAdapter(input);
         const records = this.#records.filter((record) => record.target === 'inbound'
             && (!record.adapter || record.adapter === clientAdapter));
+        let dispatchSummary;
+        let reported = false;
+        const afterDispatchListeners = [];
+        const reportDispatch = async (summary) => {
+            dispatchSummary = Object.freeze({ ...summary });
+            if (reported)
+                return;
+            reported = true;
+            for (const listener of afterDispatchListeners.splice(0)) {
+                await listener(dispatchSummary);
+            }
+        };
         const dispatch = async (index) => {
             const record = records[index];
-            if (!record)
-                return terminal();
+            if (!record) {
+                const terminalResult = await terminal({ reportDispatch });
+                if (!reported) {
+                    const inferred = results.summarize?.(terminalResult)
+                        ?? { matched: false, path: 'none', replied: false };
+                    await reportDispatch(inferred);
+                }
+                return terminalResult;
+            }
             const definition = record.slot.definition;
             if (definition.target !== 'inbound')
                 throw new Error('Invalid inbound Middleware');
             const authorInput = bindOperationInput(input, record.owner, operationSnapshot);
             const context = {
-                ...createCapabilityContext(operationSnapshot, record.owner, undefined, readOperationSession(authorInput, record.adapter)?.signal), input: authorInput,
+                ...createCapabilityContext({ snapshot: operationSnapshot, ownerId: record.owner, admission: undefined, signal: readOperationSession(authorInput, record.adapter)?.signal }), input: authorInput,
+                onAfterDispatch(listener) {
+                    if (typeof listener !== 'function') {
+                        throw new TypeError('Middleware onAfterDispatch listener must be a function');
+                    }
+                    afterDispatchListeners.push(listener);
+                },
             };
             Object.defineProperty(context, 'session', {
                 enumerable: true, get: () => readOperationSession(authorInput, record.adapter),
@@ -84,6 +109,9 @@ export class MiddlewareIndex {
             Object.defineProperty(context, '$client', {
                 enumerable: true, get: () => readOperationClient(authorInput, record.adapter),
             });
+            Object.defineProperty(context, 'dispatch', {
+                enumerable: true, get: () => dispatchSummary,
+            });
             Object.freeze(context);
             let active = true;
             let nextCalled = false;
@@ -107,7 +135,7 @@ export class MiddlewareIndex {
             };
             let returned;
             try {
-                returned = await definition.handle(context, next);
+                returned = await definition.handle.call(context, context, next);
             }
             catch (error) {
                 // Drain an admitted child before the owning generation lease can close.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/middleware",
-  "version": "1.1.12",
+  "version": "1.1.14",
   "description": "Convention-based Middleware Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -16,8 +16,8 @@
     "src"
   ],
   "dependencies": {
-    "@zhin.js/feature-kit": "1.1.11",
-    "@zhin.js/plugin-runtime": "1.1.19"
+    "@zhin.js/plugin-runtime": "1.1.21",
+    "@zhin.js/feature-kit": "1.1.13"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/definition.ts

@@ -18,6 +18,13 @@ export type MiddlewareTarget = 'inbound' | 'outbound';
 export type MiddlewareNext = () => Promise<MiddlewareContinuation>;
 export type OutboundMiddlewareNext = () => Promise<void>;
 
+export interface InboundDispatchSummary {
+  readonly matched: boolean;
+  readonly path: 'button' | 'command' | 'handler' | 'none';
+  readonly handlerId?: string;
+  readonly replied: boolean;
+}
+
 export interface MiddlewareContext<
   TInput = unknown,
   TConfig = unknown,
@@ -28,6 +35,8 @@ export interface MiddlewareContext<
   /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
   readonly $client: AdapterClient<TAdapter>;
   readonly session: OperationSession<TAdapter> | undefined;
+  readonly dispatch?: InboundDispatchSummary;
+  onAfterDispatch?(listener: (summary: InboundDispatchSummary) => void | Promise<void>): void;
 }
 
 /** Shared metadata for the public inbound and outbound definition contracts. */
@@ -71,15 +80,16 @@ declare module '@zhin.js/plugin-runtime' {
 type AuthoringForAdapter<TInput, TConfig, TAdapter extends string | undefined> =
   Omit<MiddlewareDefinitionBase<TAdapter>, '$feature' | 'phase' | 'order'> & {
     readonly phase?: MiddlewarePhase;
+    readonly stage?: MiddlewarePhase;
     readonly order?: number;
   } & (
-    | { readonly target?: 'inbound'; handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: MiddlewareNext): unknown }
+    | { readonly target?: 'inbound'; handle(this: MiddlewareContext<TInput, TConfig, TAdapter>, context: MiddlewareContext<TInput, TConfig, TAdapter>, next: MiddlewareNext): unknown }
     | {
         readonly target: 'outbound';
         /** Opt in to cumulative prefixes. Previously published text, format and addressing must stay stable;
          * do not repeat approvals, external sends or other side effects. */
         readonly incremental?: true;
-        handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: OutboundMiddlewareNext): void | Promise<void>;
+        handle(this: MiddlewareContext<TInput, TConfig, TAdapter>, context: MiddlewareContext<TInput, TConfig, TAdapter>, next: OutboundMiddlewareNext): void | Promise<void>;
       }
   );
 
@@ -92,6 +102,21 @@ export type MiddlewareAuthoringDefinition<TInput, TConfig> =
       }
     }[RegisteredAdapterName];
 
+/**
+ * Returned by `defineMiddleware.withConfig<Config>()`: fixes the plugin config type while
+ * keeping inbound/outbound input inference intact.
+ *
+ * @public
+ */
+export interface MiddlewareDefiner<TConfig> {
+  <TInput = unknown>(
+    definition: Extract<MiddlewareAuthoringDefinition<TInput, TConfig>, { readonly target: 'outbound' }>,
+  ): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, { readonly target: 'outbound' }>>;
+  <TInput = unknown>(
+    definition: Extract<MiddlewareAuthoringDefinition<TInput, TConfig>, { readonly target?: 'inbound' }>,
+  ): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, { readonly target: 'inbound' }>>;
+}
+
 export function defineMiddleware<TInput = unknown, TConfig = unknown>(
   definition: Extract<MiddlewareAuthoringDefinition<TInput, TConfig>, { readonly target: 'outbound' }>,
 ): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, { readonly target: 'outbound' }>>;
@@ -109,7 +134,7 @@ export function defineMiddleware<TInput = unknown, TConfig = unknown>(
     && (typeof adapter !== 'string' || adapter.trim() === '')) {
     throw new TypeError('Middleware adapter must be a non-empty string');
   }
-  const phase = definition.phase ?? 'before-dispatch';
+  const phase = definition.phase ?? (definition as { readonly stage?: MiddlewarePhase }).stage ?? 'before-dispatch';
   if (phase !== 'before-dispatch' && phase !== 'after-dispatch') {
     throw new TypeError(`Invalid Middleware phase: ${String(phase)}`);
   }
@@ -124,6 +149,14 @@ export function defineMiddleware<TInput = unknown, TConfig = unknown>(
   >;
 }
 
+/**
+ * Fix the plugin config type first, then define the middleware.
+ */
+defineMiddleware.withConfig = function withConfig<TConfig = unknown>(): MiddlewareDefiner<TConfig> {
+  return ((definition: MiddlewareAuthoringDefinition<unknown, TConfig>) =>
+    defineMiddleware(definition as never)) as MiddlewareDefiner<TConfig>;
+};
+
 /** @internal Runtime validation for convention-discovered modules. */
 export function parseMiddlewareDefinition(value: unknown): MiddlewareDefinition {
   if (!value || typeof value !== 'object') throw invalidMiddleware();

package/src/middleware-index.ts

@@ -7,6 +7,7 @@ import {
   readOperationSession,
 } from '@zhin.js/feature-kit';
 import type {
+  InboundDispatchSummary,
   MiddlewareContext,
   MiddlewareDefinition,
   MiddlewarePhase,
@@ -15,10 +16,16 @@ import type {
 } from './definition.js';
 import { continuationBrand, type MiddlewareContinuation } from './continuation.js';
 
+/** @internal Terminal control passed to inbound terminal callbacks to publish dispatch summary before after-dispatch unwinds. */
+export interface InboundTerminalControl {
+  reportDispatch(summary: InboundDispatchSummary): Promise<void>;
+}
+
 /** @internal Transmission-neutral result policy supplied by the composition layer. */
 export interface MiddlewareResultPolicy<TResult> {
   stop(owner: PluginId): TResult;
   replace(owner: PluginId, value: unknown, downstream: TResult | undefined): TResult;
+  summarize?(result: TResult): InboundDispatchSummary | undefined;
 }
 
 /** @internal Runtime continuation result. */
@@ -96,7 +103,7 @@ export class MiddlewareIndex {
       if (!record) return terminal();
       const authorInput = bindOperationInput(input, record.owner, operationSnapshot);
       const context = {
-        ...createCapabilityContext(operationSnapshot, record.owner, undefined, readOperationSession(authorInput, record.adapter)?.signal),
+        ...createCapabilityContext({ snapshot: operationSnapshot, ownerId: record.owner, admission: undefined, signal: readOperationSession(authorInput, record.adapter)?.signal }),
         input: authorInput,
       } as MiddlewareContext<TInput>;
       Object.defineProperty(context, 'session', {
@@ -109,7 +116,7 @@ export class MiddlewareIndex {
       Object.freeze(context);
       const definition = record.slot.definition;
       if (definition.target !== 'outbound') throw new Error('Invalid outbound Middleware');
-      const result = await definition.handle(context, () => dispatch(index + 1));
+      const result = await definition.handle.call(context, context, () => dispatch(index + 1));
       if (result !== undefined) throw new TypeError('Outbound Middleware must use input.replace(), not return content');
     };
     await dispatch(0);
@@ -118,21 +125,46 @@ export class MiddlewareIndex {
   /** Unwinds one inbound operation before its caller performs any automatic reply. */
   async runInbound<TInput, TResult>(
     input: TInput,
-    terminal: () => Promise<TResult>,
+    terminal: (control: InboundTerminalControl) => Promise<TResult>,
     results: MiddlewareResultPolicy<TResult>,
     operationSnapshot: RuntimeSnapshot = this.snapshot,
   ): Promise<TResult> {
     const clientAdapter = operationClientAdapter(input);
     const records = this.#records.filter((record) => record.target === 'inbound'
       && (!record.adapter || record.adapter === clientAdapter));
+    let dispatchSummary: InboundDispatchSummary | undefined;
+    let reported = false;
+    const afterDispatchListeners: Array<(summary: InboundDispatchSummary) => void | Promise<void>> = [];
+    const reportDispatch = async (summary: InboundDispatchSummary): Promise<void> => {
+      dispatchSummary = Object.freeze({ ...summary });
+      if (reported) return;
+      reported = true;
+      for (const listener of afterDispatchListeners.splice(0)) {
+        await listener(dispatchSummary);
+      }
+    };
     const dispatch = async (index: number): Promise<TResult> => {
       const record = records[index];
-      if (!record) return terminal();
+      if (!record) {
+        const terminalResult = await terminal({ reportDispatch });
+        if (!reported) {
+          const inferred = results.summarize?.(terminalResult)
+            ?? { matched: false, path: 'none' as const, replied: false };
+          await reportDispatch(inferred);
+        }
+        return terminalResult;
+      }
       const definition = record.slot.definition;
       if (definition.target !== 'inbound') throw new Error('Invalid inbound Middleware');
       const authorInput = bindOperationInput(input, record.owner, operationSnapshot);
       const context = {
-        ...createCapabilityContext(operationSnapshot, record.owner, undefined, readOperationSession(authorInput, record.adapter)?.signal), input: authorInput,
+        ...createCapabilityContext({ snapshot: operationSnapshot, ownerId: record.owner, admission: undefined, signal: readOperationSession(authorInput, record.adapter)?.signal }), input: authorInput,
+        onAfterDispatch(listener: (summary: InboundDispatchSummary) => void | Promise<void>) {
+          if (typeof listener !== 'function') {
+            throw new TypeError('Middleware onAfterDispatch listener must be a function');
+          }
+          afterDispatchListeners.push(listener);
+        },
       } as MiddlewareContext<TInput>;
       Object.defineProperty(context, 'session', {
         enumerable: true, get: () => readOperationSession(authorInput, record.adapter),
@@ -140,6 +172,9 @@ export class MiddlewareIndex {
       Object.defineProperty(context, '$client', {
         enumerable: true, get: () => readOperationClient(authorInput, record.adapter),
       });
+      Object.defineProperty(context, 'dispatch', {
+        enumerable: true, get: () => dispatchSummary,
+      });
       Object.freeze(context);
       let active = true;
       let nextCalled = false;
@@ -161,7 +196,7 @@ export class MiddlewareIndex {
       };
       let returned: unknown;
       try {
-        returned = await definition.handle(context, next);
+        returned = await definition.handle.call(context, context, next);
       } catch (error) {
         // Drain an admitted child before the owning generation lease can close.
         await nextTask?.catch(() => undefined);