adminforth 2.58.5 → 2.59.0

package/dist/spa/src/types/adapters/ChatSurfaceAdapter.ts

@@ -0,0 +1,84 @@
+import type { AdminUser } from "../Common.js";
+import type { IAdminForth } from "../Back.js";
+
+export type ChatSurfaceRequestContext = {
+  body: unknown;
+  headers: Record<string, unknown>;
+  abortSignal: AbortSignal;
+  rawRequest?: unknown;
+  rawResponse?: unknown;
+};
+
+export type ChatSurfaceIncomingMessage = {
+  surface: string;
+  prompt: string;
+  externalConversationId: string;
+  externalUserId: string;
+  userTimeZone?: string;
+  modeName?: string | null;
+  metadata?: Record<string, unknown>;
+};
+
+export type ChatSurfaceEvent =
+  | {
+      type: "text_delta";
+      delta: string;
+    }
+  | {
+      type: "reasoning_delta";
+      delta: string;
+    }
+  | {
+      type: "tool_call";
+      event: unknown;
+    }
+  | {
+      type: "done";
+      text: string;
+    }
+  | {
+      type: "error";
+      message: string;
+    };
+
+export interface ChatSurfaceEventSink {
+  emit(event: ChatSurfaceEvent): void | Promise<void>;
+  close?(): void | Promise<void>;
+}
+
+export interface ChatSurfaceAdapter {
+  /**
+   * Stable surface identifier used in webhook URLs and session ids.
+   */
+  name: string;
+
+  /**
+   * Validates adapter configuration during plugin initialization.
+   */
+  validate(): void;
+
+  /**
+   * Converts an incoming surface webhook/request into an AdminForth Agent prompt.
+   * Return null when the request is not a supported chat message.
+   */
+  parseIncomingMessage(
+    ctx: ChatSurfaceRequestContext,
+  ): ChatSurfaceIncomingMessage | null | Promise<ChatSurfaceIncomingMessage | null>;
+
+  /**
+   * Creates a response sink for sending agent events back to the external surface.
+   */
+  createEventSink(
+    ctx: ChatSurfaceRequestContext,
+    incoming: ChatSurfaceIncomingMessage,
+  ): ChatSurfaceEventSink | Promise<ChatSurfaceEventSink>;
+
+  /**
+   * Maps an external surface user to an authorized AdminForth admin user.
+   * Return null to reject the incoming chat message.
+   */
+  resolveAdminUser(input: {
+    adminforth: IAdminForth;
+    incoming: ChatSurfaceIncomingMessage;
+  }): AdminUser | null | Promise<AdminUser | null>;
+}

package/dist/spa/src/types/adapters/EmailAdapter.ts

@@ -11,14 +11,14 @@ export interface EmailAdapter {
    * @param from - The sender's email address
    * @param to - The recipient's email address
    * @param text - The plain text version of the email
-   * @param html - The HTML version of the email
+   * @param html - The optional HTML version of the email
    * @param subject - The subject of the email
    */
   sendEmail(
     from: string,
     to: string,
     text: string,
-    html: string,
+    html: string | undefined,
     subject: string
   ): Promise<{
     error?: string;

package/dist/spa/src/types/adapters/index.ts

@@ -1,4 +1,11 @@
 export type { EmailAdapter } from './EmailAdapter.js';
+export type {
+	ChatSurfaceAdapter,
+	ChatSurfaceEvent,
+	ChatSurfaceEventSink,
+	ChatSurfaceIncomingMessage,
+	ChatSurfaceRequestContext,
+} from './ChatSurfaceAdapter.js';
 export type {
 	CompletionAdapter,
 	CompletionAdapterLangChainAgentPurpose,

package/dist/types/adapters/ChatSurfaceAdapter.d.ts

@@ -0,0 +1,66 @@
+import type { AdminUser } from "../Common.js";
+import type { IAdminForth } from "../Back.js";
+export type ChatSurfaceRequestContext = {
+    body: unknown;
+    headers: Record<string, unknown>;
+    abortSignal: AbortSignal;
+    rawRequest?: unknown;
+    rawResponse?: unknown;
+};
+export type ChatSurfaceIncomingMessage = {
+    surface: string;
+    prompt: string;
+    externalConversationId: string;
+    externalUserId: string;
+    userTimeZone?: string;
+    modeName?: string | null;
+    metadata?: Record<string, unknown>;
+};
+export type ChatSurfaceEvent = {
+    type: "text_delta";
+    delta: string;
+} | {
+    type: "reasoning_delta";
+    delta: string;
+} | {
+    type: "tool_call";
+    event: unknown;
+} | {
+    type: "done";
+    text: string;
+} | {
+    type: "error";
+    message: string;
+};
+export interface ChatSurfaceEventSink {
+    emit(event: ChatSurfaceEvent): void | Promise<void>;
+    close?(): void | Promise<void>;
+}
+export interface ChatSurfaceAdapter {
+    /**
+     * Stable surface identifier used in webhook URLs and session ids.
+     */
+    name: string;
+    /**
+     * Validates adapter configuration during plugin initialization.
+     */
+    validate(): void;
+    /**
+     * Converts an incoming surface webhook/request into an AdminForth Agent prompt.
+     * Return null when the request is not a supported chat message.
+     */
+    parseIncomingMessage(ctx: ChatSurfaceRequestContext): ChatSurfaceIncomingMessage | null | Promise<ChatSurfaceIncomingMessage | null>;
+    /**
+     * Creates a response sink for sending agent events back to the external surface.
+     */
+    createEventSink(ctx: ChatSurfaceRequestContext, incoming: ChatSurfaceIncomingMessage): ChatSurfaceEventSink | Promise<ChatSurfaceEventSink>;
+    /**
+     * Maps an external surface user to an authorized AdminForth admin user.
+     * Return null to reject the incoming chat message.
+     */
+    resolveAdminUser(input: {
+        adminforth: IAdminForth;
+        incoming: ChatSurfaceIncomingMessage;
+    }): AdminUser | null | Promise<AdminUser | null>;
+}
+//# sourceMappingURL=ChatSurfaceAdapter.d.ts.map

package/dist/types/adapters/ChatSurfaceAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatSurfaceAdapter.d.ts","sourceRoot":"","sources":["../../../types/adapters/ChatSurfaceAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB,EAAE,MAAM,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;OAGG;IACH,oBAAoB,CAClB,GAAG,EAAE,yBAAyB,GAC7B,0BAA0B,GAAG,IAAI,GAAG,OAAO,CAAC,0BAA0B,GAAG,IAAI,CAAC,CAAC;IAElF;;OAEG;IACH,eAAe,CACb,GAAG,EAAE,yBAAyB,EAC9B,QAAQ,EAAE,0BAA0B,GACnC,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAExD;;;OAGG;IACH,gBAAgB,CAAC,KAAK,EAAE;QACtB,UAAU,EAAE,WAAW,CAAC;QACxB,QAAQ,EAAE,0BAA0B,CAAC;KACtC,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;CAClD"}

package/dist/types/adapters/ChatSurfaceAdapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ChatSurfaceAdapter.js.map

package/dist/types/adapters/ChatSurfaceAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatSurfaceAdapter.js","sourceRoot":"","sources":["../../../types/adapters/ChatSurfaceAdapter.ts"],"names":[],"mappings":""}

package/dist/types/adapters/EmailAdapter.d.ts

@@ -9,10 +9,10 @@ export interface EmailAdapter {
      * @param from - The sender's email address
      * @param to - The recipient's email address
      * @param text - The plain text version of the email
-     * @param html - The HTML version of the email
+     * @param html - The optional HTML version of the email
      * @param subject - The subject of the email
      */
-    sendEmail(from: string, to: string, text: string, html: string, subject: string): Promise<{
+    sendEmail(from: string, to: string, text: string, html: string | undefined, subject: string): Promise<{
         error?: string;
         ok?: boolean;
     }>;

package/dist/types/adapters/EmailAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EmailAdapter.d.ts","sourceRoot":"","sources":["../../../types/adapters/EmailAdapter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAE3B;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;;;;OAOG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,EAAE,CAAC,EAAE,OAAO,CAAC;KACd,CAAC,CAAC;CACJ"}
+{"version":3,"file":"EmailAdapter.d.ts","sourceRoot":"","sources":["../../../types/adapters/EmailAdapter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAE3B;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;;;;OAOG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,EAAE,CAAC,EAAE,OAAO,CAAC;KACd,CAAC,CAAC;CACJ"}

package/dist/types/adapters/index.d.ts

@@ -1,4 +1,5 @@
 export type { EmailAdapter } from './EmailAdapter.js';
+export type { ChatSurfaceAdapter, ChatSurfaceEvent, ChatSurfaceEventSink, ChatSurfaceIncomingMessage, ChatSurfaceRequestContext, } from './ChatSurfaceAdapter.js';
 export type { CompletionAdapter, CompletionAdapterLangChainAgentPurpose, CompletionAdapterLangChainAgentSpec, CompletionReasoningEffort, LangChainAgentCompletionAdapter, CompletionRequest, CompletionStreamEvent, CompletionTool, } from './CompletionAdapter.js';
 export type { ImageGenerationAdapter } from './ImageGenerationAdapter.js';
 export type { KeyValueAdapter } from './KeyValueAdapter.js';

package/dist/types/adapters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../types/adapters/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EACX,iBAAiB,EACjB,sCAAsC,EACtC,mCAAmC,EACnC,yBAAyB,EACzB,+BAA+B,EAC/B,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EACX,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,GACd,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../types/adapters/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EACX,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,GACzB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,iBAAiB,EACjB,sCAAsC,EACtC,mCAAmC,EACnC,yBAAyB,EACzB,+BAA+B,EAC/B,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EACX,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,GACd,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adminforth",
-  "version": "2.58.5",
+  "version": "2.59.0",
   "description": "OpenSource Agent-Native forth-generation admin panel",
   "keywords": [
     "adminforth",