@metad/contracts 3.8.3 → 3.9.0-beta.0

package/src/ai/xpert-project.model.d.ts

@@ -65,6 +65,9 @@ export interface IXpertProjectTaskLog extends IBasePerXpertProjectEntityModel {
     logType: 'input' | 'output' | 'error';
     content: string;
 }
+/**
+ * @deprecated use CodeXpert instead
+ */
 export interface IXpertProjectVCS extends IBasePerXpertProjectEntityModel {
     integrationId?: string;
     integration?: IIntegration;

package/src/ai/xpert-workspace.model.d.ts

@@ -16,7 +16,12 @@ export interface IXpertWorkspace extends IBasePerTenantAndOrganizationEntityMode
     environments?: IEnvironment[];
     members?: IUser[];
 }
-export type TXpertWorkspaceSettings = {};
+export type TXpertWorkspaceSettings = {
+    system?: {
+        kind?: 'org-default' | 'user-default';
+        userId?: string;
+    };
+};
 export type TXpertWorkspaceStatus = 'active' | 'deprecated' | 'archived';
 export interface IBasePerWorkspaceEntityModel extends IBasePerTenantAndOrganizationEntityModel {
     workspaceId?: string;

package/src/ai/xpert.model.d.ts

@@ -3,6 +3,7 @@ import { RunnableToolLike } from '@langchain/core/runnables';
 import { StructuredToolInterface } from '@langchain/core/tools';
 import { ITag } from '../tag-entity.model';
 import { IUser, LanguagesEnum } from '../user.model';
+import { IUserGroup } from '../user-group.model';
 import { ICopilotModel, TCopilotModel } from './copilot-model.model';
 import { IKnowledgebase, TKBRecallParams } from './knowledgebase.model';
 import { ChecklistItem, I18nObject, IPoint, ISize, TAvatar } from '../types';
@@ -159,9 +160,9 @@ export type TXpert = {
     knowledgebases?: IKnowledgebase[];
     toolsets?: IXpertToolset[];
     /**
-     * The corresponding person in charge, whose has the authority to execute this digital expert
+     * User groups that are allowed to use this published digital expert.
      */
-    managers?: IUser[];
+    userGroups?: IUserGroup[];
     /**
      * Integrations for this xpert
      */
@@ -180,6 +181,11 @@ export interface IXpert extends IBasePerWorkspaceEntityModel, TXpert {
     knowledgebase?: IKnowledgebase;
 }
 export type TXpertOptions = {
+    bootstrap?: {
+        source: 'template';
+        templateKey: string;
+        workspaceKind: 'org-default';
+    };
     knowledge?: Record<string, {
         position?: IPoint;
         size?: ISize;
@@ -475,20 +481,24 @@ export type TChatOptions = {
      */
     environment?: IEnvironment;
     /**
-     * PRO: Specify a sandbox environment container to run in
+     * Specify a sandbox environment container to run in
      */
     sandboxEnvironmentId?: string;
     /**
      * Specify additional tools
      */
     tools?: (StructuredToolInterface | RunnableToolLike)[];
+    /**
+     * Per-request runtime context forwarded to agent middleware/tools.
+     */
+    context?: Record<string, unknown>;
 };
 /**
  * Knowledgebase retrieval settings
  */
 export type TKBRetrievalSettings = {
     metadata: {
-        filtering_mode: "disabled" | "automatic" | "manual";
+        filtering_mode: 'disabled' | 'automatic' | 'manual';
         /**
          * Conditions (filter) when mode is manual
          */

package/src/ai/xpert.utils.d.ts

@@ -1,6 +1,6 @@
 import { IPoint } from '../types';
 import { IXpertAgent } from './xpert-agent.model';
-import { IXpert, TXpertTeamNode } from './xpert.model';
+import { IXpert, TXpertTeamConnection, TXpertTeamDraft, TXpertTeamNode } from './xpert.model';
 export declare function omitXpertRelations(xpert: Partial<IXpert>): {
     environmentId?: string;
     workspaceId?: string;
@@ -11,10 +11,10 @@ export declare function omitXpertRelations(xpert: Partial<IXpert>): {
     organization?: import("..").IOrganization;
     tenantId?: string;
     tenant?: import("..").ITenant;
-    id?: string;
-    createdById?: string;
+    id?: import("../types").ID;
+    createdById?: import("../types").ID;
     createdBy?: import("..").IUser;
-    updatedById?: string;
+    updatedById?: import("../types").ID;
     updatedBy?: import("..").IUser;
     createdAt?: Date;
     updatedAt?: Date;
@@ -59,7 +59,7 @@ export declare function createXpertGraph(xpert: IXpert, position: IPoint): {
         width: number;
         height: number;
     };
-    connections: import("./xpert.model").TXpertTeamConnection[];
+    connections: TXpertTeamConnection[];
 };
 export declare function locateNodes(nodes: TXpertTeamNode[], position: IPoint): {
     size: {
@@ -82,3 +82,6 @@ export declare function createXpertNodes(xpert: IXpert, position: IPoint): {
     };
 };
 export declare function createAgentConnections(agent: IXpertAgent, collaborators: IXpert[]): any[];
+export declare function replaceAgentInDraft(draft: TXpertTeamDraft, sourceKey: string, agent: Partial<IXpertAgent>, options?: {
+    requireNode?: boolean;
+}): TXpertTeamDraft;

package/src/api-key.model.d.ts

@@ -1,10 +1,68 @@
 import { IBasePerTenantAndOrganizationEntityModel } from './base-entity.model';
+import { IUser } from './user.model';
+/**
+ * Represents an API key used for authentication and authorization.
+ */
 export interface IApiKey extends IBasePerTenantAndOrganizationEntityModel {
     token: string;
     name?: string;
-    type?: string;
+    /**
+     * Stable binding kind for resolving the technical principal behind this key.
+     */
+    type?: ApiKeyBindingType;
+    /**
+     * Stable binding target id/code. Examples:
+     * - assistant => xpertId
+     * - integration => integrationId
+     * - client => clientCode
+     */
     entityId?: string;
     validUntil?: Date;
     expired?: boolean;
     lastUsedAt?: Date;
+    /**
+     * Explicit technical principal bound to this apiKey.
+     * When set, it takes precedence over type/entityId resolution.
+     */
+    userId?: string;
+    user?: IUser;
+}
+/**
+ * Optional request header used by third-party callers to explicitly set the
+ * business user represented by the current request context.
+ */
+export declare const API_PRINCIPAL_USER_ID_HEADER = "x-principal-user-id";
+/**
+ * Stable binding kinds used to resolve long-lived technical principals.
+ */
+export declare enum ApiKeyBindingType {
+    ASSISTANT = "assistant",
+    INTEGRATION = "integration",
+    CLIENT = "client",
+    /**
+     * @deprecated legacy type, do not use for new keys. Will be resolved as assistant for backward compatibility.
+     */
+    KNOWLEDGEBASE = "knowledgebase"
+}
+export type ApiPrincipalType = 'api_key' | 'client_secret';
+export interface IApiPrincipal extends IUser {
+    apiKey: IApiKey;
+    principalType: ApiPrincipalType;
+    /**
+     * Resource owner / key creator. Used for audit and ownership metadata.
+     */
+    ownerUserId?: string | null;
+    /**
+     * Technical principal resolved from apiKey.userId or stable type/entityId binding.
+     */
+    apiKeyUserId?: string | null;
+    /**
+     * Explicit business user id requested by the caller via x-principal-user-id.
+     */
+    requestedUserId?: string | null;
+    /**
+     * Original organization context requested by the caller before api-key
+     * authentication normalized the request into tenant scope.
+     */
+    requestedOrganizationId?: string | null;
 }

package/src/index.d.ts

@@ -28,6 +28,7 @@ export type { IBasePerTenantAndOrganizationEntityModel, IBasePerTenantEntityMode
 export type { IBaseEntityModel as BaseEntityModel } from './base-entity.model';
 export * from './role.model';
 export * from './user-organization.model';
+export * from './user-group.model';
 export * from './user.model';
 export * from './analytics/index';
 export * from './custom-smtp.model';
@@ -39,6 +40,7 @@ export * from './password-reset.model';
 export * from './secret-token.model';
 export * from './storage-file.model';
 export * from './visibility.model';
+export * from './scope.model';
 export * from './integration/index';
 export * from './ai/index';
 export * from './agent/index';
@@ -47,3 +49,4 @@ export * from './schedule';
 export * from './tools/index';
 export * from './plain-object.model';
 export * from './plugin';
+export * from './view-extension';

package/src/integration.model.d.ts

@@ -3,6 +3,7 @@ import { IOrganizationProjectsUpdateInput } from './organization-projects.model'
 import { IOrganizationUpdateInput } from './organization.model';
 import { ITag } from './tag-entity.model';
 import { I18nObject, IconDefinition, TAvatar, TParameterSchema } from './types';
+import { IUser } from './user.model';
 export interface IIntegration<T = any> extends IBasePerTenantAndOrganizationEntityModel {
     name: string;
     description?: string;
@@ -21,6 +22,12 @@ export interface IIntegration<T = any> extends IBasePerTenantAndOrganizationEnti
      */
     options?: T;
     tags?: ITag[];
+    /**
+     * Stable technical principal for this integration.
+     * One integration should map to one long-lived communication user.
+     */
+    userId?: string;
+    user?: IUser;
 }
 export interface IIntegrationFilter {
     integrationTypeId: string;

package/src/invite.model.d.ts

@@ -60,6 +60,8 @@ export interface ICreateEmailInvitesOutput {
 }
 export interface IInviteFindInput extends IBasePerTenantAndOrganizationEntityModel {
     invitationType?: InvitationTypeEnum;
+    email?: string;
+    status?: InviteStatusEnum;
 }
 export interface IPublicInviteFindInput {
     email: string;

package/src/plugin.d.ts

@@ -6,12 +6,39 @@ export declare const PLUGIN_LEVEL: {
     readonly SYSTEM: "system";
     readonly ORGANIZATION: "organization";
 };
+export declare const PLUGIN_SOURCE: {
+    readonly MARKETPLACE: "marketplace";
+    readonly LOCAL: "local";
+    readonly GIT: "git";
+    readonly URL: "url";
+    readonly NPM: "npm";
+    readonly CODE: "code";
+    readonly ENV: "env";
+};
+export declare const PLUGIN_CONFIGURATION_STATUS: {
+    readonly VALID: "valid";
+    readonly INVALID: "invalid";
+};
+export declare const PLUGIN_LOAD_STATUS: {
+    readonly LOADED: "loaded";
+    readonly FAILED: "failed";
+};
 /**
  * Classifies plugin scope and governance.
  * - `system`: built-in/platform-managed plugin that users cannot install/uninstall from org APIs.
  * - `organization`: tenant/org-managed plugin that can be installed and removed per organization.
  */
 export type PluginLevel = (typeof PLUGIN_LEVEL)[keyof typeof PLUGIN_LEVEL];
+export type PluginSource = (typeof PLUGIN_SOURCE)[keyof typeof PLUGIN_SOURCE];
+export type PluginConfigurationStatus = (typeof PLUGIN_CONFIGURATION_STATUS)[keyof typeof PLUGIN_CONFIGURATION_STATUS];
+export type PluginLoadStatus = (typeof PLUGIN_LOAD_STATUS)[keyof typeof PLUGIN_LOAD_STATUS];
+export type PluginScopeRelation = 'none' | 'overrides-global' | 'shadowed-by-organization';
+export interface PluginCodeSourceConfig {
+    workspacePath?: string;
+}
+export interface PluginSourceConfig extends PluginCodeSourceConfig {
+    [key: string]: unknown;
+}
 export interface PluginMeta {
     name: PluginName;
     version: string;
@@ -31,21 +58,59 @@ export interface IPlugin extends IBasePerTenantAndOrganizationEntityModel {
     pluginName: string;
     packageName: string;
     version?: string;
-    source?: 'marketplace' | 'local' | 'git' | 'url' | 'npm' | 'code' | 'env';
+    source?: PluginSource;
+    sourceConfig?: PluginSourceConfig | null;
     level?: PluginLevel;
     config: Record<string, any>;
+    configurationStatus?: PluginConfigurationStatus | null;
+    configurationError?: string | null;
+}
+export interface IPluginInstallInput {
+    pluginName: PluginName;
+    version?: string;
+    source?: PluginSource;
+    config?: Record<string, any>;
+    sourceConfig?: PluginSourceConfig;
+}
+export interface IPluginInstallResult {
+    success: boolean;
+    name: PluginName;
+    packageName: string;
+    organizationId: string;
+    currentVersion?: string;
+}
+export interface IPluginUpdateResult extends IPluginInstallResult {
+    latestVersion?: string;
+    updated: boolean;
+    previousVersion?: string;
 }
 export interface IPluginDescriptor {
     organizationId?: string;
     name: PluginName;
     meta: PluginMeta;
+    packageName?: string;
+    source?: PluginSource;
+    currentVersion?: string;
+    latestVersion?: string;
     isGlobal: boolean;
     level: PluginLevel;
     canConfigure?: boolean;
+    canRefresh?: boolean;
+    canUninstall?: boolean;
+    canUpdate?: boolean;
+    hasUpdate?: boolean;
     configSchema?: JsonSchemaObjectType;
+    configurationStatus?: PluginConfigurationStatus | null;
+    configurationError?: string | null;
+    loadStatus?: PluginLoadStatus | null;
+    loadError?: string | null;
+    effectiveInCurrentScope: boolean;
+    scopeRelation?: PluginScopeRelation;
 }
 export interface IPluginConfiguration<TConfig extends Record<string, any> = Record<string, any>> {
     pluginName: PluginName;
     config: TConfig;
     configSchema?: JsonSchemaObjectType;
+    configurationStatus?: PluginConfigurationStatus | null;
+    configurationError?: string | null;
 }

package/src/role.model.d.ts

@@ -12,13 +12,12 @@ export interface IRoleCreateInput extends IBasePerTenantEntityModel {
 export declare enum RolesEnum {
     SUPER_ADMIN = "SUPER_ADMIN",
     ADMIN = "ADMIN",
-    DATA_ENTRY = "DATA_ENTRY",
-    EMPLOYEE = "EMPLOYEE",
-    CANDIDATE = "CANDIDATE",
-    MANAGER = "MANAGER",
+    AI_BUILDER = "AI_BUILDER",
+    ANALYTICS_BUILDER = "ANALYTICS_BUILDER",
     VIEWER = "VIEWER",
     TRIAL = "TRIAL"
 }
+export declare const DEFAULT_SYSTEM_ROLES: RolesEnum[];
 export interface IRoleMigrateInput extends IBasePerTenantEntityModel {
     name: string;
     isImporting: boolean;

package/src/scope.model.d.ts

@@ -0,0 +1,9 @@
+export declare enum RequestScopeLevel {
+    TENANT = "tenant",
+    ORGANIZATION = "organization"
+}
+export interface IRequestScopeContext {
+    tenantId: string | null;
+    level: RequestScopeLevel;
+    organizationId: string | null;
+}

package/src/types.d.ts

@@ -1,6 +1,8 @@
+import ShortUniqueId from 'short-unique-id';
 import type * as z3 from "zod/v3";
 import type * as z4 from "zod/v4/core";
-export declare const uuid: (uuidLength?: number) => string;
+declare const uuidGenerator: ShortUniqueId;
+export declare const uuid: (...args: Parameters<(typeof uuidGenerator)["randomUUID"]>) => string;
 /**
  * @description
  * An entity ID. Represents a unique identifier as a string.
@@ -158,7 +160,7 @@ export type IconType = 'image' | 'svg' | 'font' | 'emoji' | 'lottie';
  * |-----------|----------------------------------|-----------------|
  * | `image`  | Raster or Base64-encoded image    | `"https://cdn.example.com/logo.png"` or `"data:image/png;base64,..."` |
  * | `svg`    | Inline SVG markup                 | `"<svg xmlns='http://www.w3.org/2000/svg'><path d='M12 2l4 20H8z'/></svg>"` |
- * | `font`   | Font icon class name              | `"fa-solid fa-user"` or `"material-icons:home"` |
+ * | `font`   | Font icon class name              | `"fa-solid fa-user"` or `"ri-home-line"` |
  * | `emoji`  | Unicode emoji character           | `"🚀"` |
  * | `lottie` | Lottie animation JSON URL         | `"https://assets.lottiefiles.com/packages/lf20_abc123.json"` |
  *
@@ -243,3 +245,4 @@ export interface IconDefinition {
 export type ZodObjectV3 = z3.ZodObject<any, any, any, any>;
 export type ZodObjectV4 = z4.$ZodObject;
 export type InteropZodObject = ZodObjectV3 | ZodObjectV4;
+export {};

package/src/user-group.model.d.ts

@@ -0,0 +1,7 @@
+import { IBasePerTenantAndOrganizationEntityModel } from './base-entity.model';
+import { IUser } from './user.model';
+export interface IUserGroup extends IBasePerTenantAndOrganizationEntityModel {
+    name: string;
+    description?: string | null;
+    members?: IUser[];
+}

package/src/view-extension/index.d.ts

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

package/src/view-extension/model.d.ts

@@ -0,0 +1,183 @@
+import type { I18nObject } from '../types';
+export type XpertViewHostType = 'integration' | 'knowledgebase' | 'agent' | 'project' | 'sandbox' | string;
+export type XpertViewSlotMode = 'tabs' | 'sections' | 'widgets' | 'sidebar';
+export type XpertViewSchemaType = 'stats' | 'table' | 'list' | 'detail' | 'raw_json';
+export type XpertViewValueType = 'text' | 'number' | 'status' | 'datetime' | 'json';
+export type XpertViewColumnDataType = 'text' | 'number' | 'date' | 'datetime' | 'status' | 'tag' | 'avatar' | 'link';
+export type XpertViewActionPlacement = 'toolbar' | 'row';
+export type XpertViewActionType = 'invoke' | 'navigate' | 'open_detail' | 'refresh';
+export type XpertViewSortDirection = 'asc' | 'desc';
+export type XpertViewFilterOperator = 'eq' | 'neq' | 'contains' | 'starts_with' | 'ends_with' | 'in' | 'gt' | 'gte' | 'lt' | 'lte';
+export type XpertViewScalar = string | number | boolean | null;
+export interface XpertViewHostContext {
+    tenantId: string;
+    organizationId?: string | null;
+    workspaceId?: string | null;
+    userId: string;
+    hostType: XpertViewHostType;
+    hostId: string;
+    module?: string;
+    route?: string;
+    permissions?: string[];
+    locale?: string;
+}
+export interface XpertResolvedViewHostContext extends XpertViewHostContext {
+    slots: XpertViewSlot[];
+    hostSnapshot?: unknown;
+}
+export interface XpertViewSlot {
+    key: string;
+    title?: I18nObject;
+    mode: XpertViewSlotMode;
+    order?: number;
+}
+export interface XpertViewSource {
+    provider: string;
+    plugin?: string;
+    version?: string;
+}
+export interface XpertViewBadge {
+    type: 'count' | 'status' | 'text';
+    value?: string | number;
+}
+export interface XpertViewPolling {
+    enabled: boolean;
+    intervalMs?: number;
+}
+export interface XpertViewCachePolicy {
+    enabled?: boolean;
+    ttlMs?: number;
+}
+export interface XpertViewQuerySchema {
+    supportsPagination?: boolean;
+    supportsSearch?: boolean;
+    supportsSort?: boolean;
+    supportsFilter?: boolean;
+    supportsCursor?: boolean;
+    supportsSelection?: boolean;
+    defaultPageSize?: number;
+}
+export interface XpertViewDataSource {
+    mode: 'platform';
+    querySchema?: XpertViewQuerySchema;
+    cache?: XpertViewCachePolicy;
+    polling?: XpertViewPolling;
+}
+export interface XpertViewFilter {
+    key: string;
+    operator?: XpertViewFilterOperator;
+    value: XpertViewScalar | XpertViewScalar[];
+}
+export interface XpertViewQuery {
+    page?: number;
+    pageSize?: number;
+    cursor?: string;
+    search?: string;
+    sortBy?: string;
+    sortDirection?: XpertViewSortDirection;
+    filters?: XpertViewFilter[];
+    selectionId?: string;
+}
+export interface XpertStatsViewSchema {
+    type: 'stats';
+    items: Array<{
+        key: string;
+        label: I18nObject;
+        valueType?: XpertViewValueType;
+    }>;
+}
+export interface XpertTableViewSchema {
+    type: 'table';
+    columns: Array<{
+        key: string;
+        label: I18nObject;
+        dataType?: XpertViewColumnDataType;
+        width?: string;
+        sortable?: boolean;
+        searchable?: boolean;
+    }>;
+    pagination?: {
+        enabled: boolean;
+        pageSize?: number;
+    };
+    search?: {
+        enabled: boolean;
+        placeholder?: I18nObject;
+    };
+}
+export interface XpertListViewSchema {
+    type: 'list';
+    item: {
+        titleKey: string;
+        subtitleKey?: string;
+        descriptionKey?: string;
+        metaKeys?: string[];
+    };
+    pagination?: {
+        enabled: boolean;
+        pageSize?: number;
+    };
+    search?: {
+        enabled: boolean;
+        placeholder?: I18nObject;
+    };
+}
+export interface XpertDetailViewSchema {
+    type: 'detail';
+    fields: Array<{
+        key: string;
+        label: I18nObject;
+        dataType?: XpertViewValueType;
+    }>;
+}
+export interface XpertRawJsonViewSchema {
+    type: 'raw_json';
+}
+export type XpertViewSchema = XpertStatsViewSchema | XpertTableViewSchema | XpertListViewSchema | XpertDetailViewSchema | XpertRawJsonViewSchema;
+export interface XpertViewActionDefinition {
+    key: string;
+    label: I18nObject;
+    icon?: string;
+    placement?: XpertViewActionPlacement;
+    actionType: XpertViewActionType;
+    confirm?: {
+        title?: I18nObject;
+        message?: I18nObject;
+    };
+    permissions?: string[];
+}
+export interface XpertExtensionViewManifest {
+    key: string;
+    title: I18nObject;
+    description?: I18nObject;
+    icon?: string;
+    hostType: XpertViewHostType;
+    slot: string;
+    order?: number;
+    visible?: boolean;
+    source: XpertViewSource;
+    permissions?: string[];
+    badge?: XpertViewBadge;
+    refreshable?: boolean;
+    polling?: XpertViewPolling;
+    view: XpertViewSchema;
+    dataSource: XpertViewDataSource;
+    actions?: XpertViewActionDefinition[];
+}
+export interface XpertViewActionRequest {
+    targetId?: string;
+}
+export interface XpertViewDataResult<TItem = unknown, TSummary = unknown> {
+    items?: TItem[];
+    item?: TItem;
+    total?: number;
+    nextCursor?: string;
+    summary?: TSummary;
+    meta?: unknown;
+}
+export interface XpertViewActionResult<TData = unknown> {
+    success: boolean;
+    message?: I18nObject;
+    data?: TData;
+    refresh?: boolean;
+}

package/index.esm.d.ts

@@ -1 +0,0 @@
-export * from "./src/index";