@xpert-ai/plugin-sdk 3.7.1 → 3.8.0

package/src/lib/channel/strategy.interface.d.ts

@@ -0,0 +1,345 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { IIntegration } from '@metad/contracts';
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Channel metadata
+ */
+export type TChatChannelMeta = {
+    /**
+     * Channel type identifier
+     */
+    type: string;
+    /**
+     * Display name
+     */
+    label: string;
+    /**
+     * Description
+     */
+    description?: string;
+    /**
+     * Icon
+     */
+    icon?: string;
+    /**
+     * JSON Schema for integration configuration
+     */
+    configSchema?: Record<string, any>;
+};
+/**
+ * Channel capabilities declaration
+ */
+export type TChatChannelCapabilities = {
+    /** Supports Markdown messages */
+    markdown: boolean;
+    /** Supports interactive cards */
+    card: boolean;
+    /** Supports card button interactions */
+    cardAction: boolean;
+    /** Supports editing/updating messages */
+    updateMessage: boolean;
+    /** Supports @mentions */
+    mention: boolean;
+    /** Supports group chat */
+    group: boolean;
+    /** Supports message threads/replies */
+    thread?: boolean;
+    /** Supports media messages (images, files) */
+    media?: boolean;
+    /** Maximum characters per message (auto-chunked if exceeded), e.g., Telegram 4096, Discord 2000 */
+    textChunkLimit?: number;
+    /** Supports streaming message updates (typewriter effect) */
+    streamingUpdate?: boolean;
+};
+/**
+ * Inbound message - unified format from different platforms
+ */
+export type TChatInboundMessage = {
+    /** Platform message ID */
+    messageId: string;
+    /** Chat ID */
+    chatId: string;
+    /** Chat type: private, group, channel, thread */
+    chatType: 'private' | 'group' | 'channel' | 'thread';
+    /** Sender ID (platform user ID) */
+    senderId: string;
+    /** Sender name */
+    senderName?: string;
+    /** Message content (text) */
+    content: string;
+    /** Content type */
+    contentType: 'text' | 'image' | 'file' | 'card_action' | 'voice';
+    /** List of mentioned users */
+    mentions?: Array<{
+        id: string;
+        name?: string;
+    }>;
+    /** Reply-to message ID */
+    replyToMessageId?: string;
+    /** Thread ID (for threaded conversations) */
+    threadId?: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Platform raw event data */
+    raw: any;
+};
+/**
+ * Card action event - triggered when user clicks card button
+ */
+export type TChatCardAction<V = unknown> = {
+    /** Action type/tag */
+    type: string;
+    /** Action value */
+    value: V;
+    /** Message ID the card belongs to */
+    messageId: string;
+    /** Chat ID */
+    chatId: string;
+    /** User ID who triggered the action */
+    userId: string;
+    /** Raw event data */
+    raw: any;
+};
+/**
+ * Chat context - used for sending messages
+ */
+export type TChatContext = {
+    /** Integration configuration */
+    integration: IIntegration;
+    /** Chat ID */
+    chatId: string;
+    /** Target user ID (for private chat) */
+    userId?: string;
+    /** Thread ID (for thread replies) */
+    threadId?: string;
+    /** Reply-to message ID */
+    replyToMessageId?: string;
+};
+/**
+ * Send result
+ */
+export type TChatSendResult = {
+    /** Success status */
+    success: boolean;
+    /** Message ID */
+    messageId?: string;
+    /** Error message */
+    error?: string;
+};
+/**
+ * Event handling context
+ */
+export type TChatEventContext<TConfig = any> = {
+    /** Integration configuration */
+    integration: IIntegration<TConfig>;
+    /** Tenant ID */
+    tenantId: string;
+    /** Organization ID */
+    organizationId: string;
+};
+/**
+ * Event handling callbacks
+ */
+export type TChatEventHandlers = {
+    /** Called when message is received */
+    onMessage?: (message: TChatInboundMessage, ctx: TChatEventContext) => Promise<void>;
+    /** Called on card interaction */
+    onCardAction?: (action: TChatCardAction, ctx: TChatEventContext) => Promise<void>;
+    /** Called when @mentioned in group chat */
+    onMention?: (message: TChatInboundMessage, ctx: TChatEventContext) => Promise<void>;
+};
+/**
+ * Chat channel interface
+ *
+ * For bidirectional messaging platforms (Lark, WeCom, DingTalk, Slack, etc.)
+ * Supports: receive message → invoke Xpert → reply message
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * @ChatChannel('lark')
+ * export class LarkChatChannel implements IChatChannel {
+ *   meta = { type: 'lark', label: 'Lark', ... }
+ *
+ *   createEventHandler(ctx, handlers) {
+ *     // Return Express middleware for handling Webhook
+ *   }
+ *
+ *   async sendText(ctx, content) {
+ *     // Send text message via Lark API
+ *   }
+ * }
+ * ```
+ */
+export interface IChatChannel<TConfig = any, TEvent = any> {
+    /**
+     * Channel metadata
+     */
+    meta: TChatChannelMeta;
+    /**
+     * Channel capabilities declaration
+     */
+    capabilities: TChatChannelCapabilities;
+    /**
+     * Create Webhook/event handler
+     *
+     * Returns Express middleware for handling inbound Webhooks.
+     * The middleware should:
+     * 1. Verify request (signature, token)
+     * 2. Parse event
+     * 3. Call appropriate handler callbacks (onMessage, onCardAction, etc.)
+     *
+     * @param ctx - Event context containing integration configuration
+     * @param handlers - Callback functions for different event types
+     * @returns Express middleware
+     */
+    createEventHandler(ctx: TChatEventContext<TConfig>, handlers: TChatEventHandlers): (req: Request, res: Response, next?: NextFunction) => Promise<void>;
+    /**
+     * Parse inbound event to unified message format
+     *
+     * @param event - Platform raw event
+     * @param ctx - Event context
+     * @returns Parsed message, or null if not a message event
+     */
+    parseInboundMessage?(event: TEvent, ctx: TChatEventContext<TConfig>): TChatInboundMessage | null;
+    /**
+     * Parse card action event
+     *
+     * @param event - Platform raw event
+     * @param ctx - Event context
+     * @returns Parsed card action, or null if not a card action event
+     */
+    parseCardAction?(event: TEvent, ctx: TChatEventContext<TConfig>): TChatCardAction | null;
+    /**
+     * Check if bot is @mentioned in message
+     *
+     * @param message - Inbound message
+     * @param botId - Bot's user ID on the platform
+     * @returns True if bot is mentioned
+     */
+    isBotMentioned?(message: TChatInboundMessage, botId: string): boolean;
+    /**
+     * Send text message
+     *
+     * @param ctx - Chat context
+     * @param content - Text content
+     * @returns Send result
+     */
+    sendText(ctx: TChatContext, content: string): Promise<TChatSendResult>;
+    /**
+     * Send Markdown message
+     *
+     * @param ctx - Chat context
+     * @param content - Markdown content
+     * @returns Send result
+     */
+    sendMarkdown?(ctx: TChatContext, content: string): Promise<TChatSendResult>;
+    /**
+     * Send interactive card
+     *
+     * @param ctx - Chat context
+     * @param card - Card content (platform-specific format)
+     * @returns Send result
+     */
+    sendCard?(ctx: TChatContext, card: any): Promise<TChatSendResult>;
+    /**
+     * Send media message (image, file)
+     *
+     * @param ctx - Chat context
+     * @param media - Media info
+     * @returns Send result
+     */
+    sendMedia?(ctx: TChatContext, media: {
+        /** Media type */
+        type: 'image' | 'file' | 'audio' | 'video';
+        /** Media URL */
+        url?: string;
+        /** Media content (Buffer) */
+        content?: Buffer;
+        /** Filename */
+        filename?: string;
+    }): Promise<TChatSendResult>;
+    /**
+     * Update/edit sent message
+     *
+     * @param ctx - Chat context
+     * @param messageId - Message ID to update
+     * @param content - New content
+     * @returns Send result
+     */
+    updateMessage?(ctx: TChatContext, messageId: string, content: string | any): Promise<TChatSendResult>;
+    /**
+     * Get bot information
+     *
+     * @param integration - Integration configuration
+     * @returns Bot info (ID, name, avatar, etc.)
+     */
+    getBotInfo?(integration: IIntegration<TConfig>): Promise<{
+        /** Bot ID */
+        id: string;
+        /** Bot name */
+        name?: string;
+        /** Bot avatar URL */
+        avatar?: string;
+    }>;
+    /**
+     * Validate integration configuration
+     *
+     * @param config - Configuration to validate
+     * @returns Validation result
+     */
+    validateConfig?(config: TConfig): Promise<{
+        /** Is valid */
+        valid: boolean;
+        /** Error list */
+        errors?: string[];
+    }>;
+    /**
+     * Test connection
+     *
+     * @param integration - Integration to test
+     * @returns Test result
+     */
+    testConnection?(integration: IIntegration<TConfig>): Promise<{
+        /** Success status */
+        success: boolean;
+        /** Message */
+        message?: string;
+    }>;
+    /**
+     * Get channel runtime status (for monitoring and operations)
+     *
+     * @param integration - Integration configuration
+     * @returns Channel status
+     */
+    getStatus?(integration: IIntegration<TConfig>): Promise<TChatChannelStatus>;
+}
+/**
+ * Channel runtime status (for monitoring)
+ */
+export type TChatChannelStatus = {
+    /** Is connected/running */
+    connected: boolean;
+    /** Last activity timestamp */
+    lastActivityAt?: number;
+    /** Last inbound message timestamp */
+    lastInboundAt?: number;
+    /** Last outbound message timestamp */
+    lastOutboundAt?: number;
+    /** Last error message */
+    error?: string;
+};
+/**
+ * Common platform message length limits
+ */
+export declare const CHAT_CHANNEL_TEXT_LIMITS: Record<string, number>;
+/**
+ * Chunk long text by specified length
+ *
+ * @param text - Text to chunk
+ * @param limit - Maximum characters per chunk
+ * @param mode - Chunking mode: 'text' splits by character, 'markdown' tries to preserve paragraphs
+ * @returns Array of chunked text
+ */
+export declare function chunkText(text: string, limit: number, mode?: 'text' | 'markdown'): string[];

package/src/lib/channel/strategy.registry.d.ts

@@ -0,0 +1,30 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import { IChatChannel } from './strategy.interface';
+/**
+ * Chat Channel Registry
+ *
+ * Manages all registered chat channel implementations.
+ * Channels are automatically discovered and registered via @ChatChannel decorator.
+ *
+ * Supports:
+ * - Organization-scoped channels
+ * - Global channels (fallback)
+ * - Plugin-based registration/removal
+ * - Dynamic channel lookup
+ *
+ * @example
+ * ```typescript
+ * // Get channel by type
+ * const channel = registry.get('lark')
+ *
+ * // List all available channels for an organization
+ * const channels = registry.list(organizationId)
+ *
+ * // Send message using a channel
+ * await channel.sendText(ctx, 'Hello!')
+ * ```
+ */
+export declare class ChatChannelRegistry extends BaseStrategyRegistry<IChatChannel> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/core/permissions/analytics.d.ts

@@ -0,0 +1,46 @@
+import type { DSCoreService } from '@metad/ocap-core';
+import type { BasePermission } from './general';
+export type AnalyticsPermissionOperation = 'dscore' | 'query' | 'model' | 'indicator' | 'create_indicator';
+/**
+ * Analytics Permission
+ * Example: { type: 'analytics', operations: ['dscore'] }
+ */
+export interface AnalyticsPermission extends BasePermission {
+    type: 'analytics';
+    operations?: AnalyticsPermissionOperation[];
+    scope?: string[];
+}
+/**
+ * System token for resolving analytics permission service from plugin context.
+ */
+export declare const ANALYTICS_PERMISSION_SERVICE_TOKEN = "XPERT_PLUGIN_ANALYTICS_PERMISSION_SERVICE";
+export interface AnalyticsResolvedChatBIModel {
+    chatbiModelId: string;
+    modelId: string;
+    modelKey?: string;
+    cubeName: string;
+    entityCaption?: string;
+    entityDescription?: string;
+    prompts?: string[];
+}
+export interface AnalyticsDSCoreInput {
+    modelIds?: string[];
+    indicatorDraft?: boolean;
+    semanticModelDraft?: boolean;
+}
+export interface AnalyticsIndicatorValidationInput {
+    modelIds?: string[];
+    semanticModelId: string;
+    modelKey?: string;
+    statement: string;
+}
+/**
+ * Analytics service exposed to plugins under permission control.
+ */
+export interface AnalyticsPermissionService {
+    resolveChatBIModels(modelIds: string[]): Promise<AnalyticsResolvedChatBIModel[]>;
+    getDSCoreService(input?: AnalyticsDSCoreInput): Promise<DSCoreService>;
+    visitChatBIModel(modelId: string, cubeName: string): Promise<void>;
+    ensureCreateIndicatorAccess(): Promise<void>;
+    validateIndicatorStatement(input: AnalyticsIndicatorValidationInput): Promise<void>;
+}

package/src/lib/core/{permissions.d.ts → permissions/general.d.ts}

@@ -1,10 +1,4 @@
-/**
- * ===============================
- * Unified Permissions Definition
- * ===============================
- * Used by Agent / Plugin developers to declare required capabilities.
- * Core system will check and inject allowed resources accordingly.
- */
+import type { IIntegration } from '@metad/contracts';
 /**
  * Base Permission type
  */
@@ -12,6 +6,7 @@ export interface BasePermission {
     type: string;
     description?: string;
 }
+export type IntegrationPermissionOperation = 'read' | 'write' | 'update' | 'delete';
 /**
  * 1. LLM Permission
  * Example: { type: 'llm', provider: 'openai', capability: 'vision' }
@@ -61,14 +56,16 @@ export interface FileSystemPermission extends BasePermission {
 export interface IntegrationPermission extends BasePermission {
     type: 'integration';
     service: string;
-    operations?: Array<'read' | 'write' | 'update' | 'delete'>;
+    operations?: IntegrationPermissionOperation[];
     scope?: string[];
 }
 /**
- * Union type for all permissions
+ * System token for resolving integration read service from plugin context.
  */
-export type Permission = LLMPermission | VectorStorePermission | KnowledgePermission | FileSystemPermission | IntegrationPermission;
+export declare const INTEGRATION_PERMISSION_SERVICE_TOKEN = "XPERT_PLUGIN_INTEGRATION_PERMISSION_SERVICE";
 /**
- * Permissions array type
+ * Read-only integration permission service exposed to plugins.
  */
-export type Permissions = Permission[];
+export interface IntegrationPermissionService {
+    read<TIntegration = IIntegration>(id: string, options?: Record<string, any>): Promise<TIntegration | null>;
+}

package/src/lib/core/permissions/handoff.d.ts

@@ -0,0 +1,36 @@
+import type { HandoffMessage, ProcessResult } from '../../agent/handoff/types';
+export type HandoffPermissionOperation = 'enqueue' | 'wait';
+/**
+ * Handoff Queue Permission
+ * Example: { type: 'handoff', operations: ['enqueue', 'wait'] }
+ */
+export interface HandoffPermission {
+    type: 'handoff';
+    operations?: HandoffPermissionOperation[];
+    scope?: string[];
+    description?: string;
+}
+/**
+ * System token for resolving handoff queue service from plugin context.
+ */
+export declare const HANDOFF_PERMISSION_SERVICE_TOKEN = "XPERT_PLUGIN_HANDOFF_PERMISSION_SERVICE";
+/**
+ * Internal system token used by core to expose the handoff queue bridge.
+ */
+export declare const HANDOFF_QUEUE_SERVICE_TOKEN = "XPERT_HANDOFF_QUEUE_SERVICE";
+export interface HandoffEnqueueOptions {
+    delayMs?: number;
+}
+export interface HandoffEnqueueAndWaitOptions extends HandoffEnqueueOptions {
+    timeoutMs?: number;
+    onEvent?: (event: unknown) => void;
+}
+/**
+ * Handoff queue service exposed to plugins under permission control.
+ */
+export interface HandoffPermissionService {
+    enqueue(message: HandoffMessage, options?: HandoffEnqueueOptions): Promise<{
+        id: string;
+    }>;
+    enqueueAndWait(message: HandoffMessage, options?: HandoffEnqueueAndWaitOptions): Promise<ProcessResult>;
+}

package/src/lib/core/permissions/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ===============================
+ * Unified Permissions Definition
+ * ===============================
+ * Used by Agent / Plugin developers to declare required capabilities.
+ * Core system will check and inject allowed resources accordingly.
+ */
+export * from './general';
+export * from './analytics';
+export * from './operation';
+export * from './handoff';
+export * from './user';
+import type { FileSystemPermission, IntegrationPermission, KnowledgePermission, LLMPermission, VectorStorePermission } from './general';
+import type { AnalyticsPermission } from './analytics';
+import type { HandoffPermission } from './handoff';
+import type { UserPermission } from './user';
+/**
+ * Union type for all permissions
+ */
+export type Permission = LLMPermission | VectorStorePermission | KnowledgePermission | FileSystemPermission | IntegrationPermission | AnalyticsPermission | UserPermission | HandoffPermission;
+/**
+ * Permissions array type
+ */
+export type Permissions = Permission[];

package/src/lib/core/permissions/operation.d.ts

@@ -0,0 +1,8 @@
+export interface PermissionOperationMetadata<TPermissionType extends string = string, TOperation extends string = string> {
+    permissionType: TPermissionType;
+    operation: TOperation;
+}
+export declare const PERMISSION_OPERATION_METADATA_KEY = "XPERT_PLUGIN_PERMISSION_OPERATION";
+export declare function RequirePermissionOperation<TPermissionType extends string, TOperation extends string>(permissionType: TPermissionType, operation: TOperation): MethodDecorator;
+export declare function getPermissionOperationMetadata(method: unknown): PermissionOperationMetadata | undefined;
+export declare function getRequiredPermissionOperation<TOperation extends string = string>(method: unknown, permissionType: string): TOperation | undefined;

package/src/lib/core/permissions/user.d.ts

@@ -0,0 +1,29 @@
+import type { IUser } from '@metad/contracts';
+import type { BasePermission } from './general';
+export type UserPermissionOperation = 'read' | 'write' | 'update' | 'delete';
+/**
+ * User Permission
+ * Example: { type: 'user', operations: ['read'] }
+ */
+export interface UserPermission extends BasePermission {
+    type: 'user';
+    operations?: UserPermissionOperation[];
+    scope?: string[];
+}
+/**
+ * System token for resolving user permission service from plugin context.
+ */
+export declare const USER_PERMISSION_SERVICE_TOKEN = "XPERT_PLUGIN_USER_PERMISSION_SERVICE";
+export interface UserProvisionByThirdPartyIdentityInput {
+    tenantId: string;
+    thirdPartyId: string;
+    profile?: Partial<Pick<IUser, 'username' | 'email' | 'mobile' | 'imageUrl' | 'firstName' | 'lastName' | 'preferredLanguage'>>;
+    defaults?: {
+        roleId?: string;
+        roleName?: string;
+    };
+}
+export interface UserPermissionService {
+    read<TUser = IUser>(criteria: Record<string, any>): Promise<TUser | null>;
+    provisionByThirdPartyIdentity<TUser = IUser>(input: UserProvisionByThirdPartyIdentityInput): Promise<TUser | null>;
+}

package/src/lib/core/utils.d.ts

@@ -1,4 +1,5 @@
 import { Logger } from '@nestjs/common';
+import { JSONSchema4 } from 'json-schema';
 export declare function loadYamlFile<T>(filePath: string, logger?: Logger, ignoreError?: boolean, defaultValue?: T): T;
 /**
  * Get the mapping from name to index from a YAML file
@@ -10,3 +11,8 @@ export declare function loadYamlFile<T>(filePath: string, logger?: Logger, ignor
 export declare function getPositionMap(folderPath: string, fileName?: string, logger?: Logger): Record<string, number>;
 export declare function getPositionList(folderPath: string, fileName?: string, logger?: Logger): string[];
 export declare function getErrorMessage(err: any): string;
+export declare class JsonSchemaValidator {
+    private ajv;
+    constructor();
+    parseAndValidate(schemaStr?: string): JSONSchema4 | undefined;
+}

package/src/lib/integration/strategy.interface.d.ts

@@ -5,5 +5,7 @@ export type TIntegrationStrategyParams = {
 export interface IntegrationStrategy<T = unknown> {
     meta: TIntegrationProvider;
     execute(integration: IIntegration<T>, payload: TIntegrationStrategyParams): Promise<any>;
-    validateConfig?(config: T): Promise<void>;
+    validateConfig?(config: T, integration?: IIntegration<T>): Promise<void | {
+        webhookUrl: string;
+    }>;
 }

package/src/lib/sandbox/index.d.ts

@@ -0,0 +1,8 @@
+export * from './protocol';
+export * from './sandbox';
+export * from './sandbox.decorator';
+export * from './sandbox.interface';
+export * from './sandbox.registry';
+export * from './sandbox.interface';
+export * from './sandbox.decorator';
+export * from './sandbox.registry';