@xpert-ai/plugin-sdk 3.6.1 → 3.6.3

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.6.1",
+  "version": "3.6.3",
   "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xpert-ai/xpert.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xpert-ai/xpert/issues"
+  },
   "dependencies": {},
   "main": "./index.cjs.js",
   "module": "./index.esm.js",
@@ -13,12 +20,14 @@
     "@metad/contracts": "*",
     "@nestjs/common": "*",
     "@nestjs/core": "*",
-    "@nestjs/microservices": "*",
     "lodash-es": "*",
     "i18next-fs-backend": "*",
     "i18next": "*",
-    "zod": "*",
+    "jsonwebtoken": "*",
     "fs": "*",
-    "path": "*"
+    "path": "*",
+    "passport-jwt": "*",
+    "stream": "*",
+    "zod": "*"
   }
 }

package/src/index.d.ts

@@ -9,4 +9,5 @@ export * from './lib/vectorstore/index';
 export * from './lib/rag/index';
 export * from './lib/toolset/index';
 export * from './lib/core/index';
+export * from './lib/data/index';
 export * from './lib/ai-model/index';

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

@@ -0,0 +1,2 @@
+export * from './request-context';
+export * from './request-context.middleware';

package/src/lib/core/context/request-context.d.ts

@@ -0,0 +1,46 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { IUser, LanguagesEnum, PermissionsEnum, RolesEnum } from '@metad/contracts';
+import type { IncomingMessage, ServerResponse } from 'http';
+import { AsyncLocalStorage } from 'node:async_hooks';
+export declare class RequestContext {
+    readonly request: IncomingMessage;
+    readonly response: ServerResponse;
+    readonly reqId: string;
+    readonly userId?: string;
+    readonly extras: Record<string, any>;
+    constructor(request: IncomingMessage, response: ServerResponse, reqId: string, userId?: string, extras?: Record<string, any>);
+    static currentRequestContext(): RequestContext;
+    static currentRequest(): IncomingMessage;
+    static currentTenantId(): string;
+    static currentUserId(): string;
+    static currentRoleId(): string;
+    static currentUser(throwError?: boolean): IUser;
+    static hasPermission(permission: PermissionsEnum | string, throwError?: boolean): boolean;
+    /**
+     * Retrieves the language code from the headers of the current request.
+     * @returns The language code (LanguagesEnum) extracted from the headers, or the default language (ENGLISH) if not found.
+     */
+    static getLanguageCode(): LanguagesEnum;
+    static getOrganizationId(): string;
+    static hasPermissions(findPermissions: Array<PermissionsEnum | string>, throwError?: boolean): boolean;
+    static hasAnyPermission(findPermissions: PermissionsEnum[], throwError?: boolean): boolean;
+    static currentToken(throwError?: boolean): any;
+    /**
+     * Checks if the current user has a specific role.
+     * @param {RolesEnum} role - The role to check.
+     * @param {boolean} throwError - Flag indicating whether to throw an error if the role is not granted.
+     * @returns {boolean} - True if the user has the role, otherwise false.
+     */
+    static hasRole(role: RolesEnum, throwError?: boolean): boolean;
+    /**
+     * Checks if the current request context has any of the specified roles.
+     *
+     * @param roles - An array of roles to check.
+     * @param throwError - Whether to throw an error if no roles are found.
+     * @returns True if any of the required roles are found, otherwise false.
+     */
+    static hasRoles(roles: RolesEnum[], throwError?: boolean): boolean;
+}
+export declare const als: AsyncLocalStorage<RequestContext>;
+export declare function getRequestContext(): RequestContext;

package/src/lib/core/context/request-context.middleware.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="node" />
+import { NestMiddleware } from '@nestjs/common';
+import { IncomingMessage, ServerResponse } from 'node:http';
+export declare class RequestContextMiddleware implements NestMiddleware {
+    use(req: IncomingMessage, _res: ServerResponse, next: () => void): void;
+}
+export declare function runWithRequestContext(req: IncomingMessage, res: ServerResponse, next: () => void): void;

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

@@ -3,3 +3,4 @@ export * from './permissions';
 export * from './schema';
 export * from './i18n';
 export * from './utils';
+export * from './context/index';

package/src/lib/data/datasource/adapter.strategy.d.ts

@@ -0,0 +1,20 @@
+import { IDataSourceStrategy } from './strategy.interface';
+import { AdapterBaseOptions, DBQueryRunner, DBQueryRunnerType } from './types';
+/**
+ * Helper base class to wrap existing adapter query runner implementations
+ * into datasource strategies consumable by the plugin SDK.
+ */
+export declare abstract class AdapterDataSourceStrategy<TOptions extends AdapterBaseOptions = AdapterBaseOptions> implements IDataSourceStrategy<TOptions> {
+    private readonly runnerClass;
+    private readonly extraArgs;
+    abstract readonly type: string;
+    abstract readonly name: string;
+    readonly description?: string;
+    private configurationSchemaCache;
+    protected constructor(runnerClass: DBQueryRunnerType, extraArgs?: unknown[]);
+    create(options: TOptions): Promise<DBQueryRunner>;
+    configurationSchema(): Promise<Record<string, unknown>>;
+    teardown(runner: DBQueryRunner): Promise<void>;
+    protected instantiateRunner(options: TOptions | undefined): DBQueryRunner;
+    getClassType(): DBQueryRunnerType;
+}

package/src/lib/data/datasource/index.d.ts

@@ -0,0 +1,5 @@
+export * from './strategy.decorator';
+export * from './strategy.interface';
+export * from './strategy.registry';
+export * from './adapter.strategy';
+export * from './types';

package/src/lib/data/datasource/strategy.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const DATASOURCE_STRATEGY = "DATASOURCE_STRATEGY";
+export declare const DataSourceStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;

package/src/lib/data/datasource/strategy.interface.d.ts

@@ -0,0 +1,19 @@
+import { AdapterBaseOptions, DBQueryRunner, DBQueryRunnerType } from "./types";
+export interface IDataSourceStrategy<TOptions extends AdapterBaseOptions = AdapterBaseOptions> {
+    readonly type: string;
+    readonly name: string;
+    readonly description?: string;
+    /**
+     * Create a query runner for the given data source options.
+     */
+    create(options: TOptions): Promise<DBQueryRunner> | DBQueryRunner;
+    /**
+     * Optional configuration schema description for UI generation.
+     */
+    configurationSchema?(): Promise<Record<string, unknown>> | Record<string, unknown>;
+    /**
+     * Cleanup hook invoked when a runner is no longer needed.
+     */
+    teardown?(runner: DBQueryRunner): Promise<void> | void;
+    getClassType(): DBQueryRunnerType;
+}

package/src/lib/data/datasource/strategy.registry.d.ts

@@ -0,0 +1,7 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { IDataSourceStrategy } from './strategy.interface';
+import { AdapterBaseOptions } from './types';
+export declare class DataSourceStrategyRegistry<TOptions extends AdapterBaseOptions = any> extends BaseStrategyRegistry<IDataSourceStrategy<TOptions>> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/data/datasource/types.d.ts

@@ -0,0 +1,255 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import * as _axios from 'axios';
+import { Readable } from 'stream';
+import { IColumnDef, IDSSchema, IDSTable } from '@metad/contracts';
+export { IColumnDef, IDSSchema, IDSTable } from '@metad/contracts';
+/**
+ * The base options for DB adapters
+ */
+export interface AdapterBaseOptions {
+    /**
+     * Ref to debug in `createConnection` of `mysql`
+     */
+    debug?: boolean;
+    /**
+     * Ref to trace in `createConnection` of `mysql`
+     */
+    trace?: boolean;
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+}
+export declare enum DBSyntaxEnum {
+    SQL = "sql",
+    MDX = "mdx"
+}
+export declare enum DBProtocolEnum {
+    SQL = "sql",
+    XMLA = "xmla"
+}
+/**
+ * Options of single query
+ */
+export interface QueryOptions {
+    catalog?: string;
+    headers?: Record<string, string>;
+}
+export interface QueryResult<T = unknown> {
+    status: 'OK' | 'ERROR';
+    data?: Array<T>;
+    columns?: Array<IColumnDef>;
+    stats?: any;
+    error?: string;
+}
+/**
+ * Duties:
+ * - Convert error messages into a unified format
+ * - Connect different types of data sources
+ */
+export interface DBQueryRunner {
+    type: string;
+    name: string;
+    syntax: DBSyntaxEnum;
+    protocol: DBProtocolEnum;
+    host: string;
+    port: number | string;
+    jdbcDriver: string;
+    configurationSchema: Record<string, unknown>;
+    jdbcUrl(schema?: string): string;
+    /**
+     * Execute a sql query
+     *
+     * @param sql
+     */
+    run(sql: string): Promise<any>;
+    /**
+     * Execute a sql query with options
+     *
+     * @param query
+     * @param options
+     */
+    runQuery(query: string, options?: QueryOptions): Promise<QueryResult | any>;
+    /**
+     * Get catalog (schema or database) list in data source
+     */
+    getCatalogs(): Promise<IDSSchema[]>;
+    /**
+     * Get schema of table in catalog (schema or database)
+     *
+     * @param catalog
+     * @param tableName
+     */
+    getSchema(catalog?: string, tableName?: string): Promise<IDSSchema[]>;
+    /**
+     * Describe a sql query result schema
+     *
+     * @param catalog
+     * @param statement
+     */
+    describe(catalog: string, statement: string): Promise<{
+        columns?: IDSTable['columns'];
+    }>;
+    /**
+     * Ping the db
+     */
+    ping(): Promise<void>;
+    /**
+     * Create a new catalog (schema) in database
+     *
+     * @param catalog
+     */
+    createCatalog?(catalog: string): Promise<void>;
+    /**
+     * Create or append table data
+     *
+     * @param params
+     * @param options
+     */
+    import(params: CreationTable, options?: QueryOptions): Promise<any>;
+    /**
+     * Drop a table
+     *
+     * @param name Table name
+     * @param options
+     */
+    dropTable(name: string, options?: QueryOptions): Promise<void>;
+    /**
+     * Teardown all resources:
+     * - close connection
+     *
+     */
+    teardown(): Promise<void>;
+}
+export type DBQueryRunnerType = new (options?: AdapterBaseOptions, ...args: unknown[]) => DBQueryRunner;
+export interface ColumnDef {
+    /**
+     * Key of data object
+     */
+    name: string;
+    /**
+     * Name of table column
+     */
+    fieldName: string;
+    /**
+     * Object value type, convert to db type
+     */
+    type: string;
+    /**
+     * Is primary key column
+     */
+    isKey: boolean;
+    /**
+     * length of type for column: varchar, decimal ...
+     */
+    length?: number;
+    /**
+     * fraction of type for decimal
+     */
+    fraction?: number;
+}
+export interface CreationTable {
+    catalog?: string;
+    table?: string;
+    name: string;
+    columns: ColumnDef[];
+    data?: any[];
+    file?: File;
+    mergeType?: 'APPEND' | 'DELETE' | 'MERGE';
+    format?: 'csv' | 'json' | 'parquet' | 'orc' | 'data';
+    columnSeparator?: string;
+    withHeader?: number;
+}
+export declare abstract class BaseQueryRunner<T extends AdapterBaseOptions = AdapterBaseOptions> implements DBQueryRunner {
+    type: string;
+    name: string;
+    syntax: DBSyntaxEnum;
+    protocol: DBProtocolEnum;
+    jdbcDriver: string;
+    abstract get host(): string;
+    abstract get port(): number | string;
+    options: T;
+    jdbcUrl(schema?: string): string;
+    get configurationSchema(): any;
+    constructor(options?: T);
+    run(sql: string): Promise<any>;
+    abstract runQuery(query: string, options?: QueryOptions): Promise<QueryResult>;
+    abstract getCatalogs(): Promise<IDSSchema[]>;
+    abstract getSchema(catalog?: string, tableName?: string): Promise<IDSSchema[]>;
+    describe(catalog: string, statement: string): Promise<{
+        columns?: IDSTable['columns'];
+    }>;
+    abstract ping(): Promise<void>;
+    import({ name, columns, data }: {
+        name: any;
+        columns: any;
+        data: any;
+    }, options?: {
+        catalog?: string;
+    }): Promise<void>;
+    dropTable(name: string, options?: any): Promise<void>;
+    abstract teardown(): Promise<void>;
+}
+export interface HttpAdapterOptions extends AdapterBaseOptions {
+    url?: string;
+}
+export declare abstract class BaseHTTPQueryRunner<T extends HttpAdapterOptions = HttpAdapterOptions> extends BaseQueryRunner<T> {
+    get url(): string;
+    get host(): string;
+    get port(): number | string;
+    get configurationSchema(): {};
+    get(): Promise<_axios.AxiosResponse<any, any>>;
+    post(data: any, options?: any): Promise<_axios.AxiosResponse<any, any>>;
+}
+/**
+ * Adapter options for sql db
+ */
+export interface SQLAdapterOptions extends AdapterBaseOptions {
+    url?: string;
+    /**
+     * Database name, used as catalog
+     */
+    catalog?: string;
+    use_ssl?: boolean;
+    ssl_cacert?: string;
+    version?: number;
+}
+export declare abstract class BaseSQLQueryRunner<T extends SQLAdapterOptions = SQLAdapterOptions> extends BaseQueryRunner<T> {
+    syntax: DBSyntaxEnum;
+    protocol: DBProtocolEnum;
+    get host(): string;
+    get port(): string | number;
+    abstract createCatalog?(catalog: string): Promise<void>;
+    ping(): Promise<void>;
+}
+export interface File {
+    /** Name of the form field associated with this file. */
+    fieldname: string;
+    /** Name of the file on the uploader's computer. */
+    originalname: string;
+    /**
+     * Value of the `Content-Transfer-Encoding` header for this file.
+     * @deprecated since July 2015
+     * @see RFC 7578, Section 4.7
+     */
+    encoding: string;
+    /** Value of the `Content-Type` header for this file. */
+    mimetype: string;
+    /** Size of the file in bytes. */
+    size: number;
+    /**
+     * A readable stream of this file. Only available to the `_handleFile`
+     * callback for custom `StorageEngine`s.
+     */
+    stream: Readable;
+    /** `DiskStorage` only: Directory to which this file has been uploaded. */
+    destination: string;
+    /** `DiskStorage` only: Name of this file within `destination`. */
+    filename: string;
+    /** `DiskStorage` only: Full path to the uploaded file. */
+    path: string;
+    /** `MemoryStorage` only: A Buffer containing the entire file. */
+    buffer: Buffer;
+}

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

@@ -0,0 +1 @@
+export * from './datasource/index';

package/src/lib/rag/image/strategy.interface.d.ts

@@ -27,5 +27,5 @@ export interface IImageUnderstandingStrategy<TConfig extends TImageUnderstanding
     /**
      * Understand image files (e.g., OCR, VLM, Chart Parsing)
      */
-    understandImages(doc: IKnowledgeDocument<ChunkMetadata>, config: TConfig): Promise<TImageUnderstandingResult>;
+    understandImages(doc: IKnowledgeDocument, config: TConfig): Promise<TImageUnderstandingResult>;
 }