@kimposoft/plugin-sdk 0.0.0-stage → 1.1.0-tp.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/NOTICE +9 -0
- package/README.md +48 -2
- package/package.json +145 -4
- package/src/action-designer.ts +267 -0
- package/src/attachment-open.ts +574 -0
- package/src/attachment-url.ts +235 -0
- package/src/auth/index.ts +6 -0
- package/src/auth/qrcode.ts +519 -0
- package/src/auth/types.ts +261 -0
- package/src/display-style.ts +532 -0
- package/src/editor-frame.ts +625 -0
- package/src/editor-session.ts +1214 -0
- package/src/editor-testing.ts +838 -0
- package/src/editor.ts +1720 -0
- package/src/frame-transport.ts +516 -0
- package/src/frontend-routes.ts +99 -0
- package/src/hooks.ts +48 -0
- package/src/host-caps.ts +93 -0
- package/src/i18n.ts +238 -0
- package/src/im-panel.ts +132 -0
- package/src/image-tools.ts +91 -0
- package/src/index.ts +125 -0
- package/src/interactive-session.ts +94 -0
- package/src/nahida-im.ts +391 -0
- package/src/nahida-ws.ts +23 -0
- package/src/org-directory.ts +78 -0
- package/src/oz-realtime.ts +144 -0
- package/src/page.ts +591 -0
- package/src/print.ts +393 -0
- package/src/surface.ts +310 -0
- package/src/theme-mocks.ts +140 -0
- package/src/theme.ts +125 -0
- package/src/ui-fixtures/attachment.ts +24 -0
- package/src/ui-fixtures/confirm.ts +16 -0
- package/src/ui-fixtures/entity-picker.ts +24 -0
- package/src/ui-fixtures/expression-editor.ts +52 -0
- package/src/ui-fixtures/image-cropper.ts +23 -0
- package/src/ui-fixtures/index.ts +17 -0
- package/src/ui-fixtures/org-tri-picker.ts +19 -0
- package/src/ui-fixtures/prompt.ts +19 -0
- package/src/ui-fixtures/record-picker.ts +17 -0
- package/src/ui-fixtures/template-picker.ts +13 -0
- package/src/ui-mocks.ts +264 -0
- package/src/ui.ts +491 -0
- package/src/workflow-designer.ts +475 -0
package/src/index.ts
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
// @kimposoft/plugin-sdk —— Kimpo 插件前端契约的唯一真相来源。
|
|
2
|
+
// 宿主前端与各插件都依赖本包,彼此不互相 import,依赖单向无环。
|
|
3
|
+
// 与 Go 侧 SDK 对称:editor ↔ direction/editor,hooks ↔ direction/hooks。
|
|
4
|
+
export * from './editor';
|
|
5
|
+
export * from './hooks';
|
|
6
|
+
// 通用 surface 挂载契约(SurfaceType / SurfaceCreateInput / SurfaceMountResult / definePluginSurface)。
|
|
7
|
+
export * from './surface';
|
|
8
|
+
// 平台交互会话:资源绑定、Host 自动续租、插件零凭据的统一生命周期 handle。
|
|
9
|
+
export * from './interactive-session';
|
|
10
|
+
// 宿主 UI 服务总线(平台级 ui.* 能力域):表达式编辑器 / 通讯录选人器等常用界面由宿主渲染一次,
|
|
11
|
+
// 插件经 createHostUi(hostBridge) 命令式唤起,零 UI 代码。不属任何插件分类独占。
|
|
12
|
+
export * from './ui';
|
|
13
|
+
// 宿主 UI 服务总线 mock 工厂:createMockHostUi / createMockHostUiBridge,供插件在自己的
|
|
14
|
+
// playground / 单测里不启动宿主也能把交互跑通(confirm/cancel/not-wired 三档,用法见
|
|
15
|
+
// ui-mocks.ts 头注释)。
|
|
16
|
+
export * from './ui-mocks';
|
|
17
|
+
// 宿主设计数值(theme 能力)契约面:RGB / HostThemeTokens / HostTheme 类型 +
|
|
18
|
+
// readHostTheme / toCss 读取函数;只有类型与函数,不含任何数值常量。
|
|
19
|
+
export * from './theme';
|
|
20
|
+
// theme 能力 mock 工厂:createMockHostTheme(可手动触发变化,数值仅测试用),供插件单测 / playground 使用。
|
|
21
|
+
export * from './theme-mocks';
|
|
22
|
+
// 宿主 UI 服务总线四个服务的请求/结果夹具(纯 JSON、零函数),插件写测试可直接 import,
|
|
23
|
+
// 不必自己造一份合法的 request/result。
|
|
24
|
+
export * from './ui-fixtures';
|
|
25
|
+
// 多语言契约与两级查找 helper(HostI18n / createPluginI18n / COMMON_VOCABULARY),
|
|
26
|
+
// 插件自带语言包 miss 时回落宿主中央语言包。
|
|
27
|
+
export * from './i18n';
|
|
28
|
+
// page-slot 页面级插件契约(模板历史记录列表页):
|
|
29
|
+
// TemplateRecordsPageProps / PageRecordListClient / PageNavigationClient / PagePermissionClient。
|
|
30
|
+
export * from './page';
|
|
31
|
+
// 字段展示样式格式化纯函数:formatDisplayStyleValue / isDateTimeDisplayStyle /
|
|
32
|
+
// isNumericDisplayStyle,口径逐档对齐表格编辑器填报态单元格,供记录列表等其他消费方复用。
|
|
33
|
+
// 同文件还导出日期时间「自定义」展示样式(440)格式串函数:CUSTOM_DATETIME_DISPLAY_STYLE /
|
|
34
|
+
// renderDatetimePattern / validateDatetimePattern / datetimePatternGrain / datetimePatternToExcelNumFmt /
|
|
35
|
+
// readDatetimePattern 等,消费方从字段 format_rule_json 读格式串后传给 formatDisplayStyleValue。
|
|
36
|
+
export * from './display-style';
|
|
37
|
+
// 附件值 → 地址纯函数:parseAttachmentItems / attachmentItemUrls / attachmentItemsSummary /
|
|
38
|
+
// isImageItem / isAttachmentField / isImageField / isImageDisplayStyle,表格编辑器候选、历史记录页、宿主内置
|
|
39
|
+
// 回退视图与视图设计器预览共用,各处不得自行拼接宿主图片 / 附件端点;地址自动携带查询上下文读票据(qt)。
|
|
40
|
+
export * from './attachment-url';
|
|
41
|
+
// 附件插件(surface attachment.open)前端契约:AttachmentOpenDecl / AttachmentOpenContext / AttachmentEditSession /
|
|
42
|
+
// OpenAttachmentRequest / defineAttachmentOpenSurface / matchesAttachmentOpenAccepts。宿主附件外壳按 manifest
|
|
43
|
+
// capabilities.attachment_open 路由并挂载;调用方统一经 ui.openAttachment 打开附件,不再自带查看器。
|
|
44
|
+
export * from './attachment-open';
|
|
45
|
+
// 登录页插件(auth.login slot)前端契约:AuthKind / LoginMethod / LoginPageProps / LoginOutcome /
|
|
46
|
+
// AuthErrorCode / AuthLoginHostBridge / definePluginLoginSurface / QrCodeRenderer,
|
|
47
|
+
// 使用说明见 SDK 第三方指南 docs/third-party/auth-and-hooks.md。
|
|
48
|
+
export * from './auth';
|
|
49
|
+
// 图片工具前端契约:ImageCropRect / ImageCompressMode / ImageCropperOptions /
|
|
50
|
+
// ImageCropperResult / ImageToolsClient,挂 EditorHostBridge.imageTools。
|
|
51
|
+
export * from './image-tools';
|
|
52
|
+
// 组织架构取人前端契约(IM 前端插件等使用):OrgDept / OrgMember /
|
|
53
|
+
// OrgDirectoryClient,插件不碰组织表,薄封装宿主既有 IAM 接口。
|
|
54
|
+
export * from './org-directory';
|
|
55
|
+
// 消息与即时通讯引擎(消息引擎)正式分域业务契约与资产上传/鉴权预览能力。
|
|
56
|
+
// 根入口已有编辑器历史 AssetClient,故 IM 资产客户端在根入口显式别名;
|
|
57
|
+
// `@kimposoft/plugin-sdk/nahida-im` 子入口仍按正式契约导出 AssetClient 原名。
|
|
58
|
+
export type {
|
|
59
|
+
AssetClient as NahidaAssetClient,
|
|
60
|
+
AssetDownloadDescriptor,
|
|
61
|
+
AssetOpenDescriptor,
|
|
62
|
+
AssetPreviewKind,
|
|
63
|
+
AssetUploadInput,
|
|
64
|
+
AssetUploadTask,
|
|
65
|
+
NahidaAssetReference,
|
|
66
|
+
NahidaBusinessCard,
|
|
67
|
+
NahidaBusinessCardAction,
|
|
68
|
+
NahidaClientError,
|
|
69
|
+
NahidaConversation,
|
|
70
|
+
NahidaConversationClient,
|
|
71
|
+
NahidaConversationKind,
|
|
72
|
+
NahidaCursorPage,
|
|
73
|
+
NahidaCursorPageRequest,
|
|
74
|
+
NahidaErrorCode,
|
|
75
|
+
NahidaGroupClient,
|
|
76
|
+
NahidaGroupMember,
|
|
77
|
+
NahidaId,
|
|
78
|
+
NahidaImClient,
|
|
79
|
+
NahidaJsonObject,
|
|
80
|
+
NahidaJsonPrimitive,
|
|
81
|
+
NahidaJsonValue,
|
|
82
|
+
NahidaLogger,
|
|
83
|
+
NahidaMemberRole,
|
|
84
|
+
NahidaMemberSource,
|
|
85
|
+
NahidaMentionAll,
|
|
86
|
+
NahidaMentions,
|
|
87
|
+
NahidaMentionUser,
|
|
88
|
+
NahidaMessage,
|
|
89
|
+
NahidaMessageClient,
|
|
90
|
+
NahidaMessageContent,
|
|
91
|
+
NahidaMessageKind,
|
|
92
|
+
NahidaMessagePage,
|
|
93
|
+
NahidaNotificationClient,
|
|
94
|
+
NahidaOffsetPage,
|
|
95
|
+
NahidaPreferenceClient,
|
|
96
|
+
NahidaDndPreference,
|
|
97
|
+
NahidaCategoryPreference,
|
|
98
|
+
NahidaNotificationCategory,
|
|
99
|
+
NahidaPresenceClient,
|
|
100
|
+
NahidaPresenceMode,
|
|
101
|
+
NahidaPresenceStatus,
|
|
102
|
+
NahidaReaction,
|
|
103
|
+
NahidaSearchClient,
|
|
104
|
+
NahidaSequence,
|
|
105
|
+
NahidaSystemNotification,
|
|
106
|
+
NahidaTimeClient,
|
|
107
|
+
NahidaTimestamp,
|
|
108
|
+
NahidaUserSearchHit
|
|
109
|
+
} from './nahida-im';
|
|
110
|
+
// 消息引擎 WS 长连接前端契约:NahidaWSState /
|
|
111
|
+
// NahidaWSClient,插件经此复用宿主已持有的 WS 单例,不再自建独立连接。
|
|
112
|
+
export * from './nahida-ws';
|
|
113
|
+
export * from './oz-realtime';
|
|
114
|
+
// 平台级 hostCaps 白名单裁剪(SEC-012):WorkflowCapabilityError / pruneBridgeByCaps 等符号
|
|
115
|
+
// 是宿主 UI 服务、KimpoAI / IM 悬浮窗、动作设计器共用的平台级能力裁剪(非流程插件专属)。
|
|
116
|
+
export * from './host-caps';
|
|
117
|
+
// manifest capabilities.frontend.routes 的类型与自检。
|
|
118
|
+
export * from './frontend-routes';
|
|
119
|
+
|
|
120
|
+
// iframe 沙箱挂载档框架侧传输层
|
|
121
|
+
export * from './frame-transport';
|
|
122
|
+
|
|
123
|
+
// 打印方案 B 档前端契约:PrintModeBuildSpecContext / PrintJobSpec 类型与 definePrintModeBuildSpec
|
|
124
|
+
// (在沙箱框架内登记 buildSpec,宿主经框架桥 expose 调用)。
|
|
125
|
+
export * from './print';
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
// Host 交互会话是所有官方业务编辑面的唯一前端生命周期边界。
|
|
2
|
+
// 插件只拿到资源已绑定的 handle;资源身份、登录会话、编辑租约及传输凭据均由 Host 持有。
|
|
3
|
+
|
|
4
|
+
import type { HostTheme } from './theme';
|
|
5
|
+
|
|
6
|
+
/** 前端 bundle 必须声明的分域代际;宿主按声明的代际判断能否加载该 bundle。 */
|
|
7
|
+
export const INTERACTIVE_SESSION_SCHEMA_DOMAIN = 'frontend.interactive-session' as const;
|
|
8
|
+
|
|
9
|
+
/** surface manifest 用于申请 Host 注入交互会话的唯一能力键。 */
|
|
10
|
+
export const INTERACTIVE_SESSION_CAPABILITY = 'platform.interactiveSession' as const;
|
|
11
|
+
|
|
12
|
+
export const INTERACTIVE_SESSION_MODES = ['view', 'create', 'edit'] as const;
|
|
13
|
+
export type InteractiveSessionMode = (typeof INTERACTIVE_SESSION_MODES)[number];
|
|
14
|
+
|
|
15
|
+
export const INTERACTIVE_SESSION_STATES = ['opening', 'active', 'conflicted', 'lost', 'auth_ended', 'closed'] as const;
|
|
16
|
+
export type InteractiveSessionState = (typeof INTERACTIVE_SESSION_STATES)[number];
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Host 判定的终态原因。插件只能据此冻结界面和提示用户,不能自行重建租约或 runtime。
|
|
20
|
+
* auth-ended 到达时 Host 已先 scrub 敏感内存,通知仅用于让插件收敛 UI。
|
|
21
|
+
*/
|
|
22
|
+
// 早期值域里的 'resource-invalidated' / 'workspace-revoked' 从未产生过(Host 侧从未派发),已移除。
|
|
23
|
+
export const INTERACTIVE_SESSION_LOSS_REASONS = [
|
|
24
|
+
'auth-ended',
|
|
25
|
+
'lease-conflict',
|
|
26
|
+
'lease-stale',
|
|
27
|
+
'lease-expired',
|
|
28
|
+
'offline',
|
|
29
|
+
'transport-expired',
|
|
30
|
+
'runtime-closed',
|
|
31
|
+
'host-unavailable'
|
|
32
|
+
] as const;
|
|
33
|
+
export type InteractiveSessionLossReason = (typeof INTERACTIVE_SESSION_LOSS_REASONS)[number];
|
|
34
|
+
|
|
35
|
+
export const INTERACTIVE_SESSION_CLOSE_REASONS = [
|
|
36
|
+
'user',
|
|
37
|
+
'surface-replaced',
|
|
38
|
+
'resource-switch',
|
|
39
|
+
'application-logout',
|
|
40
|
+
'host-shutdown'
|
|
41
|
+
] as const;
|
|
42
|
+
export type InteractiveSessionCloseReason = (typeof INTERACTIVE_SESSION_CLOSE_REASONS)[number];
|
|
43
|
+
|
|
44
|
+
export interface InteractiveSessionConflict {
|
|
45
|
+
readonly ownerDisplayName?: string;
|
|
46
|
+
readonly isSelf: boolean;
|
|
47
|
+
readonly retryAfterMs?: number;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** 插件可观察的最小快照;刻意不包含资源键、auth session、租约或传输 token。 */
|
|
51
|
+
export interface InteractiveSessionSnapshot {
|
|
52
|
+
readonly mode: InteractiveSessionMode;
|
|
53
|
+
readonly state: InteractiveSessionState;
|
|
54
|
+
readonly lossReason: InteractiveSessionLossReason | null;
|
|
55
|
+
readonly dirty: boolean;
|
|
56
|
+
/** Host 最近向插件公开的围栏 epoch;0 表示当前没有已观察到的编辑租约。 */
|
|
57
|
+
readonly epoch: number;
|
|
58
|
+
readonly expiresAt: string | null;
|
|
59
|
+
readonly serverTime: string | null;
|
|
60
|
+
/** 仅用于判断 Host 是否已原子换入更新的传输凭据,不含任何凭据内容。 */
|
|
61
|
+
readonly transportCredentialRevision: number;
|
|
62
|
+
readonly conflict: Readonly<InteractiveSessionConflict> | null;
|
|
63
|
+
/** 仅用于按钮显隐;真正的管理员权限必须由 Host 端点重新校验。 */
|
|
64
|
+
readonly canAdminRelease: boolean;
|
|
65
|
+
/** blocked/view 场景能否请求进入编辑态;最终裁决仍由 Host 完成。 */
|
|
66
|
+
readonly canRequestEdit: boolean;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export type InteractiveSessionChangeListener = (snapshot: Readonly<InteractiveSessionSnapshot>) => void;
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* 资源已绑定的交互会话 handle。
|
|
73
|
+
*
|
|
74
|
+
* 不提供 renew/acquire:Host 自动续租并持有全部凭据。observedEpoch 只用于条件重试/释放,
|
|
75
|
+
* 不能被插件解释成资源身份或授权证明。
|
|
76
|
+
*/
|
|
77
|
+
export interface InteractiveSessionHandle {
|
|
78
|
+
readonly snapshot: Readonly<InteractiveSessionSnapshot>;
|
|
79
|
+
markDirty(dirty: boolean): void;
|
|
80
|
+
onChange(listener: InteractiveSessionChangeListener): () => void;
|
|
81
|
+
requestEdit(observedEpoch: number): Promise<void>;
|
|
82
|
+
adminRelease(observedEpoch: number): Promise<void>;
|
|
83
|
+
close(reason: InteractiveSessionCloseReason): Promise<void>;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** 所有官方 surface hostBridge 的平台级基座。 */
|
|
87
|
+
export interface InteractiveSessionHostBridge {
|
|
88
|
+
readonly interactiveSession: InteractiveSessionHandle;
|
|
89
|
+
/**
|
|
90
|
+
* 宿主设计数值(theme 能力):常驻可见,不需要在 manifest 声明、不受 hostCaps 裁剪;
|
|
91
|
+
* 老宿主可能缺失,读取请用 readHostTheme(bridge)。
|
|
92
|
+
*/
|
|
93
|
+
readonly theme?: HostTheme;
|
|
94
|
+
}
|
package/src/nahida-im.ts
ADDED
|
@@ -0,0 +1,391 @@
|
|
|
1
|
+
// 消息与即时通讯引擎(消息引擎)的前端业务契约。
|
|
2
|
+
//
|
|
3
|
+
// 本文件只定义插件 SDK 的稳定能力面:宿主负责把 REST、IAM、资产
|
|
4
|
+
// 服务和鉴权适配到这些接口;插件不得据此反推出 URL、Cookie 或连接生命周期。
|
|
5
|
+
|
|
6
|
+
/** 后端 int64 标识符在前端始终保持字符串,禁止转换成 JavaScript number。 */
|
|
7
|
+
export type NahidaId = string;
|
|
8
|
+
|
|
9
|
+
/** ISO 8601 / RFC3339 时间串。时间展示必须由插件结合宿主时区完成。 */
|
|
10
|
+
export type NahidaTimestamp = string;
|
|
11
|
+
|
|
12
|
+
/** 消息 seq 是会话内单调递增序号,不是全局消息标识。 */
|
|
13
|
+
export type NahidaSequence = number;
|
|
14
|
+
|
|
15
|
+
export type NahidaJsonPrimitive = string | number | boolean | null;
|
|
16
|
+
export type NahidaJsonValue = NahidaJsonPrimitive | NahidaJsonObject | NahidaJsonValue[];
|
|
17
|
+
export interface NahidaJsonObject {
|
|
18
|
+
readonly [key: string]: NahidaJsonValue;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** 可供宿主映射 HTTP、权限或业务错误的稳定错误码。 */
|
|
22
|
+
export type NahidaErrorCode =
|
|
23
|
+
| 'NAHIDA_ACCESS_DENIED'
|
|
24
|
+
| 'NAHIDA_NOT_FOUND'
|
|
25
|
+
| 'NAHIDA_CONFLICT'
|
|
26
|
+
| 'NAHIDA_CURSOR_INVALID'
|
|
27
|
+
| 'NAHIDA_MESSAGE_REVOKED'
|
|
28
|
+
| 'NAHIDA_MEMBER_MANAGED_BY_ORG'
|
|
29
|
+
| 'NAHIDA_CONVERSATION_READONLY'
|
|
30
|
+
| 'NAHIDA_ASSET_UNAVAILABLE'
|
|
31
|
+
| 'NAHIDA_CAPABILITY_UNAVAILABLE'
|
|
32
|
+
| 'NAHIDA_UNKNOWN';
|
|
33
|
+
|
|
34
|
+
/** SDK 调用失败时宿主抛出的结构化错误;插件不可依赖 HTTP 状态或内部响应信封。 */
|
|
35
|
+
export interface NahidaClientError {
|
|
36
|
+
readonly code: NahidaErrorCode;
|
|
37
|
+
readonly message: string;
|
|
38
|
+
readonly retryable: boolean;
|
|
39
|
+
readonly details?: Readonly<Record<string, NahidaJsonValue>>;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** 插件关键路径日志经宿主汇聚,不能自行直连日志服务。 */
|
|
43
|
+
export interface NahidaLogger {
|
|
44
|
+
debug(message: string, context?: Readonly<Record<string, NahidaJsonValue>>): void;
|
|
45
|
+
info(message: string, context?: Readonly<Record<string, NahidaJsonValue>>): void;
|
|
46
|
+
warn(message: string, context?: Readonly<Record<string, NahidaJsonValue>>): void;
|
|
47
|
+
error(message: string, context?: Readonly<Record<string, NahidaJsonValue>>): void;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** 基于 offset 的结果页,供兼容传统通知目录等数据源。 */
|
|
51
|
+
export interface NahidaOffsetPage<T> {
|
|
52
|
+
readonly items: readonly T[];
|
|
53
|
+
readonly total: number;
|
|
54
|
+
readonly offset: number;
|
|
55
|
+
readonly limit: number;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** 不透明游标分页;插件只保存并回传 cursor,不能解析或自行构造它。 */
|
|
59
|
+
export interface NahidaCursorPage<T> {
|
|
60
|
+
readonly items: readonly T[];
|
|
61
|
+
readonly nextCursor: string | null;
|
|
62
|
+
readonly prevCursor?: string | null;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export interface NahidaCursorPageRequest {
|
|
66
|
+
readonly cursor?: string;
|
|
67
|
+
readonly limit?: number;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export type NahidaConversationKind = 'single' | 'group' | 'department' | 'business' | 'system-notification';
|
|
71
|
+
export type NahidaMessageKind = 'text' | 'image' | 'file' | 'system' | 'card' | 'recall-tombstone';
|
|
72
|
+
export type NahidaMemberRole = 'member' | 'admin' | 'owner';
|
|
73
|
+
export type NahidaMemberSource = 'manual' | 'organization' | 'business';
|
|
74
|
+
|
|
75
|
+
/** 视频以 file + mimeType/video 元数据表达,首期刻意没有 video 消息类型。 */
|
|
76
|
+
export interface NahidaAssetReference {
|
|
77
|
+
readonly assetId: NahidaId;
|
|
78
|
+
readonly fileName: string;
|
|
79
|
+
readonly byteSize: number;
|
|
80
|
+
readonly mimeType: string;
|
|
81
|
+
readonly width?: number;
|
|
82
|
+
readonly height?: number;
|
|
83
|
+
readonly durationMs?: number;
|
|
84
|
+
readonly checksumSha256?: string;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
export interface NahidaMentionAll {
|
|
88
|
+
readonly all: true;
|
|
89
|
+
}
|
|
90
|
+
export interface NahidaMentionUser {
|
|
91
|
+
readonly userId: NahidaId;
|
|
92
|
+
}
|
|
93
|
+
export type NahidaMentions = NahidaMentionAll | readonly NahidaMentionUser[];
|
|
94
|
+
|
|
95
|
+
/** 可由 renderer registry 消费的业务卡片,不把业务 DTO 泄漏为 IM wire DTO。 */
|
|
96
|
+
export interface NahidaBusinessCard {
|
|
97
|
+
readonly cardType?: string;
|
|
98
|
+
readonly schemaVersion?: 1;
|
|
99
|
+
readonly rendererKey: string;
|
|
100
|
+
readonly version?: string;
|
|
101
|
+
readonly title?: string;
|
|
102
|
+
readonly summary?: string;
|
|
103
|
+
readonly link?: { readonly route: string };
|
|
104
|
+
readonly capability?: string;
|
|
105
|
+
readonly actionPayload?: NahidaJsonValue;
|
|
106
|
+
readonly state?: 'pending' | 'done' | 'ignored' | 'agreed' | 'expired';
|
|
107
|
+
readonly data: NahidaJsonObject;
|
|
108
|
+
readonly actions?: readonly NahidaBusinessCardAction[];
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
export interface NahidaBusinessCardAction {
|
|
112
|
+
readonly key: string;
|
|
113
|
+
readonly label: string;
|
|
114
|
+
readonly style?: 'default' | 'primary' | 'danger';
|
|
115
|
+
readonly requiresComment?: boolean;
|
|
116
|
+
readonly disabled?: boolean;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
export interface NahidaMessageContent {
|
|
120
|
+
readonly text?: string;
|
|
121
|
+
readonly asset?: NahidaAssetReference;
|
|
122
|
+
readonly systemCode?: string;
|
|
123
|
+
readonly systemParams?: NahidaJsonObject;
|
|
124
|
+
readonly card?: NahidaBusinessCard;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
export interface NahidaReaction {
|
|
128
|
+
readonly emoji: string;
|
|
129
|
+
readonly count: number;
|
|
130
|
+
readonly reactedByMe: boolean;
|
|
131
|
+
readonly userIds?: readonly NahidaId[];
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
export interface NahidaMessage {
|
|
135
|
+
readonly id: NahidaId;
|
|
136
|
+
readonly conversationId: NahidaId;
|
|
137
|
+
readonly seq: NahidaSequence;
|
|
138
|
+
readonly senderId: NahidaId;
|
|
139
|
+
readonly senderDisplayName?: string;
|
|
140
|
+
readonly senderAvatarAssetId?: NahidaId;
|
|
141
|
+
/** 发送幂等键由客户端生成;重试时必须复用同一值。 */
|
|
142
|
+
readonly clientMsgId: string;
|
|
143
|
+
readonly kind: NahidaMessageKind;
|
|
144
|
+
readonly content: NahidaMessageContent;
|
|
145
|
+
readonly mentions?: NahidaMentions;
|
|
146
|
+
readonly replyToSeq?: NahidaSequence;
|
|
147
|
+
readonly forwardOf?: { readonly conversationId: NahidaId; readonly seq: NahidaSequence };
|
|
148
|
+
readonly reactions?: readonly NahidaReaction[];
|
|
149
|
+
readonly createdAt: NahidaTimestamp;
|
|
150
|
+
readonly revokedAt?: NahidaTimestamp;
|
|
151
|
+
readonly revokedBy?: NahidaId;
|
|
152
|
+
readonly editedAt?: NahidaTimestamp;
|
|
153
|
+
/** 宿主按当前查看者投影的私聊卡片动作状态;发送方和非目标用户看不到。 */
|
|
154
|
+
readonly cardAction?: {
|
|
155
|
+
readonly source: 'nahida-message';
|
|
156
|
+
readonly state: 'pending' | 'ignored' | 'agreed' | 'expired';
|
|
157
|
+
readonly busy?: boolean;
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
export interface NahidaConversation {
|
|
162
|
+
readonly id: NahidaId;
|
|
163
|
+
readonly kind: NahidaConversationKind;
|
|
164
|
+
readonly displayName: string;
|
|
165
|
+
readonly avatarAssetId?: NahidaId;
|
|
166
|
+
readonly peerUserId?: NahidaId;
|
|
167
|
+
/** department 会话以稳定 orgUnitId 绑定,改名/移动不改变会话身份。 */
|
|
168
|
+
readonly department?: { readonly orgUnitId: NahidaId; readonly includeChildren: false };
|
|
169
|
+
readonly business?: { readonly objectType: string; readonly objectId: NahidaId };
|
|
170
|
+
readonly memberCount: number;
|
|
171
|
+
readonly lastSeq: NahidaSequence;
|
|
172
|
+
readonly readSeq: NahidaSequence;
|
|
173
|
+
readonly deliveredSeq: NahidaSequence;
|
|
174
|
+
readonly mentionSeq: NahidaSequence;
|
|
175
|
+
readonly unreadCount: number;
|
|
176
|
+
readonly hasMention: boolean;
|
|
177
|
+
readonly muted: boolean;
|
|
178
|
+
readonly pinned: boolean;
|
|
179
|
+
readonly hidden: boolean;
|
|
180
|
+
readonly readonly: boolean;
|
|
181
|
+
readonly muteAll?: boolean;
|
|
182
|
+
readonly currentMemberSendMuted?: boolean;
|
|
183
|
+
readonly announcementMessageId?: NahidaId;
|
|
184
|
+
/**
|
|
185
|
+
* 当前登录成员在群聊/部门群/业务会话中的真实角色与成员来源。
|
|
186
|
+
* 单聊和系统通知固定为 null;插件不得从 ownerUserId 或会话类型猜测角色。
|
|
187
|
+
*/
|
|
188
|
+
readonly currentMemberRole: NahidaMemberRole | null;
|
|
189
|
+
readonly currentMemberSource: NahidaMemberSource | null;
|
|
190
|
+
readonly lastMessage?: NahidaMessage;
|
|
191
|
+
readonly updatedAt: NahidaTimestamp;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/** 系统通知是 UI 虚拟会话投影,不与 im_message 合并或伪造消息 ID。 */
|
|
195
|
+
export interface NahidaSystemNotification {
|
|
196
|
+
readonly id: NahidaId;
|
|
197
|
+
readonly type: string;
|
|
198
|
+
readonly title: string;
|
|
199
|
+
readonly content: string;
|
|
200
|
+
readonly link?: string;
|
|
201
|
+
readonly readAt: NahidaTimestamp | null;
|
|
202
|
+
readonly createdAt: NahidaTimestamp;
|
|
203
|
+
readonly card?: NahidaBusinessCard;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
export interface NahidaConversationClient {
|
|
207
|
+
list(request?: NahidaCursorPageRequest): Promise<NahidaCursorPage<NahidaConversation>>;
|
|
208
|
+
get(conversationId: NahidaId): Promise<NahidaConversation>;
|
|
209
|
+
createSingle(peerUserId: NahidaId): Promise<NahidaConversation>;
|
|
210
|
+
createGroup(input: { readonly name: string; readonly memberUserIds: readonly NahidaId[] }): Promise<NahidaConversation>;
|
|
211
|
+
patch(conversationId: NahidaId, patch: Readonly<Partial<Pick<NahidaConversation, 'muted' | 'pinned' | 'hidden'>>>): Promise<NahidaConversation>;
|
|
212
|
+
hide(conversationId: NahidaId): Promise<void>;
|
|
213
|
+
getDepartmentConversation(orgUnitId: NahidaId): Promise<NahidaConversation | null>;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
export interface NahidaMessagePage extends NahidaCursorPage<NahidaMessage> {
|
|
217
|
+
readonly latestSeq: NahidaSequence;
|
|
218
|
+
readonly gapDetected?: boolean;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
export interface NahidaMessageClient {
|
|
222
|
+
listSince(conversationId: NahidaId, afterSeq: NahidaSequence, limit?: number): Promise<NahidaMessagePage>;
|
|
223
|
+
listBefore(conversationId: NahidaId, beforeSeq: NahidaSequence, limit?: number): Promise<NahidaMessagePage>;
|
|
224
|
+
listAround(conversationId: NahidaId, aroundSeq: NahidaSequence, limit?: number): Promise<NahidaMessagePage>;
|
|
225
|
+
send(input: {
|
|
226
|
+
readonly conversationId: NahidaId;
|
|
227
|
+
readonly clientMsgId: string;
|
|
228
|
+
readonly kind: Exclude<NahidaMessageKind, 'system' | 'recall-tombstone'>;
|
|
229
|
+
readonly content: NahidaMessageContent;
|
|
230
|
+
readonly mentions?: NahidaMentions;
|
|
231
|
+
readonly replyToSeq?: NahidaSequence;
|
|
232
|
+
}): Promise<{ readonly message: NahidaMessage; readonly isNew: boolean }>;
|
|
233
|
+
revoke(messageId: NahidaId): Promise<void>;
|
|
234
|
+
forward(input: { readonly conversationId: NahidaId; readonly clientMsgId: string; readonly source: { readonly conversationId: NahidaId; readonly seq: NahidaSequence } }): Promise<{ readonly message: NahidaMessage; readonly isNew: boolean }>;
|
|
235
|
+
setReaction(messageId: NahidaId, emoji: string, active: boolean): Promise<NahidaReaction>;
|
|
236
|
+
listReactions(messageId: NahidaId): Promise<readonly NahidaReaction[]>;
|
|
237
|
+
getReadReceipt(conversationId: NahidaId, seq: NahidaSequence): Promise<{ readonly mode: 'roster' | 'count' | 'disabled'; readonly readCount?: number; readonly readUserIds?: readonly NahidaId[] }>;
|
|
238
|
+
ackRead(conversationId: NahidaId, readSeq: NahidaSequence): Promise<void>;
|
|
239
|
+
ackDelivered(conversationId: NahidaId, deliveredSeq: NahidaSequence): Promise<void>;
|
|
240
|
+
cardAction(messageId: NahidaId, input: { readonly key: string }): Promise<{ readonly state: 'ignored' | 'agreed' | 'expired'; readonly message?: string }>;
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
export interface NahidaGroupMember {
|
|
244
|
+
readonly userId: NahidaId;
|
|
245
|
+
readonly displayName: string;
|
|
246
|
+
readonly role: NahidaMemberRole;
|
|
247
|
+
readonly source: NahidaMemberSource;
|
|
248
|
+
readonly sendMuted?: boolean;
|
|
249
|
+
readonly joinedAt: NahidaTimestamp;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
export interface NahidaGroupClient {
|
|
253
|
+
listMembers(conversationId: NahidaId, request?: NahidaCursorPageRequest): Promise<NahidaCursorPage<NahidaGroupMember>>;
|
|
254
|
+
addMembers(conversationId: NahidaId, userIds: readonly NahidaId[]): Promise<readonly NahidaId[]>;
|
|
255
|
+
kick(conversationId: NahidaId, userId: NahidaId): Promise<void>;
|
|
256
|
+
setRole(conversationId: NahidaId, userId: NahidaId, role: NahidaMemberRole): Promise<void>;
|
|
257
|
+
leave(conversationId: NahidaId): Promise<void>;
|
|
258
|
+
dissolve(conversationId: NahidaId): Promise<void>;
|
|
259
|
+
updateInfo(conversationId: NahidaId, input: { readonly name?: string; readonly avatarAssetId?: NahidaId }): Promise<NahidaConversation>;
|
|
260
|
+
setMuteAll(conversationId: NahidaId, enabled: boolean): Promise<{ readonly changed: boolean }>;
|
|
261
|
+
setMemberSendMuted(conversationId: NahidaId, userId: NahidaId, muted: boolean): Promise<{ readonly changed: boolean }>;
|
|
262
|
+
getAnnouncement(conversationId: NahidaId): Promise<NahidaMessage | null>;
|
|
263
|
+
setAnnouncement(conversationId: NahidaId, input: { readonly mutationId: string; readonly text: string }): Promise<{ readonly message: NahidaMessage; readonly isNew: boolean }>;
|
|
264
|
+
clearAnnouncement(conversationId: NahidaId, mutationId: string): Promise<{ readonly event: NahidaMessage; readonly isNew: boolean }>;
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
export interface NahidaSearchClient {
|
|
268
|
+
searchUsers(keyword: string, request?: NahidaCursorPageRequest): Promise<NahidaCursorPage<NahidaUserSearchHit>>;
|
|
269
|
+
searchGroups(keyword: string, request?: NahidaCursorPageRequest): Promise<NahidaCursorPage<NahidaConversation>>;
|
|
270
|
+
searchConversations(keyword: string, request?: NahidaCursorPageRequest): Promise<NahidaCursorPage<NahidaConversation>>;
|
|
271
|
+
searchMessages(keyword: string, input?: Readonly<{ conversationId?: NahidaId } & NahidaCursorPageRequest>): Promise<NahidaCursorPage<NahidaMessage>>;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** IM 搜索域的轻量人员命中;完整多部门资料仍通过 OrgDirectoryClient 获取。 */
|
|
275
|
+
export interface NahidaUserSearchHit {
|
|
276
|
+
readonly userId: NahidaId;
|
|
277
|
+
readonly displayName: string;
|
|
278
|
+
readonly avatarAssetId?: NahidaId;
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
export interface NahidaNotificationClient {
|
|
282
|
+
list(request?: Readonly<{ onlyUnread?: boolean; offset?: number; limit?: number }>): Promise<NahidaOffsetPage<NahidaSystemNotification>>;
|
|
283
|
+
unreadCount(): Promise<number>;
|
|
284
|
+
markRead(input?: { readonly ids?: readonly NahidaId[]; readonly all?: boolean }): Promise<number>;
|
|
285
|
+
cardAction(notificationId: NahidaId, input: { readonly key: string; readonly comment?: string }): Promise<{ readonly forwarded: boolean; readonly message?: string }>;
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/**
|
|
289
|
+
* 在线状态三态(含 'busy'):值由宿主/后端合成——真实连接态 + 用户手动
|
|
290
|
+
* 模式(见 NahidaPreferenceClient.getPresenceMode)。'busy'=在线且手动置忙碌;隐身用户对
|
|
291
|
+
* 他人恒为 'offline'(服务端 mask,插件感知不到 invisible 本身)。追加式演进:旧消费方把
|
|
292
|
+
* 'busy' 当未知值按 'offline' 兜底即可,不破坏既有二态判定。
|
|
293
|
+
*/
|
|
294
|
+
export type NahidaPresenceStatus = 'online' | 'busy' | 'offline';
|
|
295
|
+
|
|
296
|
+
export interface NahidaPresenceClient {
|
|
297
|
+
queryUsers(userIds: readonly NahidaId[]): Promise<Readonly<Record<NahidaId, NahidaPresenceStatus>>>;
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
/** 手动在线状态模式(用户级、多端共享):auto=跟随连接态;busy=忙碌(联动免打扰);invisible=隐身 */
|
|
301
|
+
export type NahidaPresenceMode = 'auto' | 'busy' | 'invisible';
|
|
302
|
+
|
|
303
|
+
export type NahidaNotificationCategory = 'chat' | 'todo' | 'mention' | 'announcement' | 'system';
|
|
304
|
+
export interface NahidaDndPreference {
|
|
305
|
+
readonly enabled: boolean;
|
|
306
|
+
readonly startTime: string | null;
|
|
307
|
+
readonly endTime: string | null;
|
|
308
|
+
/** IANA timezone,由宿主 IAM 偏好注入和更新,IM 后端不持有该字段。 */
|
|
309
|
+
readonly timezone: string;
|
|
310
|
+
readonly urgentBypassDnd: boolean;
|
|
311
|
+
}
|
|
312
|
+
export interface NahidaCategoryPreference {
|
|
313
|
+
readonly inApp: boolean;
|
|
314
|
+
readonly mail: boolean;
|
|
315
|
+
readonly sms: boolean;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
export interface NahidaPreferenceClient {
|
|
319
|
+
getMuted(conversationId: NahidaId): Promise<boolean>;
|
|
320
|
+
updateMuted(conversationId: NahidaId, muted: boolean): Promise<void>;
|
|
321
|
+
getDnd(): Promise<NahidaDndPreference>;
|
|
322
|
+
updateDnd(input: NahidaDndPreference): Promise<void>;
|
|
323
|
+
getCategoryPrefs(): Promise<Readonly<Record<NahidaNotificationCategory, NahidaCategoryPreference>>>;
|
|
324
|
+
updateCategoryPrefs(category: NahidaNotificationCategory, prefs: NahidaCategoryPreference): Promise<void>;
|
|
325
|
+
/** 手动在线状态模式(宿主经 GET/PUT /api/v1/im/preferences/presence 透传) */
|
|
326
|
+
getPresenceMode(): Promise<NahidaPresenceMode>;
|
|
327
|
+
updatePresenceMode(mode: NahidaPresenceMode): Promise<void>;
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
export type AssetPreviewKind = 'image' | 'pdf' | 'video' | 'text' | 'download';
|
|
331
|
+
export interface AssetUploadInput {
|
|
332
|
+
readonly file: Blob;
|
|
333
|
+
readonly fileName: string;
|
|
334
|
+
readonly mimeType: string;
|
|
335
|
+
readonly signal?: AbortSignal;
|
|
336
|
+
readonly onProgress?: (progress: Readonly<{ loadedBytes: number; totalBytes: number | null }>) => void;
|
|
337
|
+
}
|
|
338
|
+
export interface AssetUploadTask {
|
|
339
|
+
readonly uploadId: string;
|
|
340
|
+
readonly result: Promise<NahidaAssetReference>;
|
|
341
|
+
/** 与 AssetClient.cancel(uploadId) 等价的任务级便捷入口。 */
|
|
342
|
+
cancel(reason?: string): void;
|
|
343
|
+
}
|
|
344
|
+
export interface AssetOpenDescriptor {
|
|
345
|
+
readonly asset: NahidaAssetReference;
|
|
346
|
+
readonly kind: AssetPreviewKind;
|
|
347
|
+
/** 宿主签发、短期有效的鉴权 URL;text 预览由宿主返回安全文本,不暴露 URL。 */
|
|
348
|
+
readonly url?: string;
|
|
349
|
+
readonly expiresAt?: NahidaTimestamp;
|
|
350
|
+
readonly downloadFileName?: string;
|
|
351
|
+
/** 仅 kind=text:宿主完成鉴权读取、UTF-8/二进制校验和上限裁剪后的纯文本。 */
|
|
352
|
+
readonly text?: string;
|
|
353
|
+
readonly truncated?: boolean;
|
|
354
|
+
readonly originalByteSize?: number;
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
|
|
358
|
+
export interface AssetDownloadDescriptor {
|
|
359
|
+
/** 宿主签发、短期有效的鉴权下载 URL。 */
|
|
360
|
+
readonly url: string;
|
|
361
|
+
readonly expiresAt?: NahidaTimestamp;
|
|
362
|
+
readonly fileName: string;
|
|
363
|
+
readonly mimeType: string;
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
/** 通用资产能力;上传和预览均经宿主鉴权,视频按 file 消息的 asset 调用本接口。 */
|
|
367
|
+
export interface AssetClient {
|
|
368
|
+
upload(input: AssetUploadInput): AssetUploadTask;
|
|
369
|
+
cancel(uploadId: string, reason?: string): void;
|
|
370
|
+
openPreview(asset: NahidaAssetReference): Promise<AssetOpenDescriptor>;
|
|
371
|
+
getDownloadURL(asset: NahidaAssetReference): Promise<AssetDownloadDescriptor>;
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
/** 时间展示只读能力;IANA timezone 来自宿主 IAM/App state,插件不得读取浏览器本地时区。 */
|
|
375
|
+
export interface NahidaTimeClient {
|
|
376
|
+
currentTimezone(): string;
|
|
377
|
+
}
|
|
378
|
+
|
|
379
|
+
/** 消息引擎正式分域客户端。没有 connect/disconnect;实时连接能力由 NahidaWSClient 另行注入。 */
|
|
380
|
+
export interface NahidaImClient {
|
|
381
|
+
readonly conversations: NahidaConversationClient;
|
|
382
|
+
readonly messages: NahidaMessageClient;
|
|
383
|
+
readonly groups: NahidaGroupClient;
|
|
384
|
+
readonly search: NahidaSearchClient;
|
|
385
|
+
readonly notifications: NahidaNotificationClient;
|
|
386
|
+
readonly presence: NahidaPresenceClient;
|
|
387
|
+
readonly preferences: NahidaPreferenceClient;
|
|
388
|
+
readonly assets: AssetClient;
|
|
389
|
+
readonly time: NahidaTimeClient;
|
|
390
|
+
readonly logger?: NahidaLogger;
|
|
391
|
+
}
|
package/src/nahida-ws.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// 消息引擎 WS host-cap 前端契约。
|
|
2
|
+
//
|
|
3
|
+
// 插件不自建 WS 连接(自建会占用户连接配额、同一帧被推两次),而是经 hostBridge.ws 复用
|
|
4
|
+
// 宿主已持有的那一条消息引擎单例连接。
|
|
5
|
+
//
|
|
6
|
+
// 🔴 连接由宿主持有,本契约只是"视图":没有 connect()/disconnect()——插件不拥有连接
|
|
7
|
+
// 生命周期(由宿主管理,与登录/登出同生命周期),只能订阅帧、
|
|
8
|
+
// 发上行帧、读状态。多个订阅者(顶栏通知角标 + IM 插件面板)共享同一条连接是设计本意。
|
|
9
|
+
export type NahidaWSState = 'connecting' | 'open' | 'disconnected';
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* 消息引擎 WS 长连接的宿主能力面(hostCaps.ws)。帧格式由宿主消息引擎定义,插件按 kind 订阅。
|
|
13
|
+
*/
|
|
14
|
+
export interface NahidaWSClient {
|
|
15
|
+
/** 订阅某个下行帧 kind(如 'im.message'/'im.revoke'/'hello')。返回取消订阅函数。 */
|
|
16
|
+
subscribe(kind: string, handler: (data: unknown) => void): () => void;
|
|
17
|
+
/** 发上行帧(协议契约 §4:仅 ack.read/ack.delivered/ping 这类轻量游标上报,发消息走 REST)。 */
|
|
18
|
+
send(kind: string, data: unknown): void;
|
|
19
|
+
/** 当前连接状态。 */
|
|
20
|
+
getState(): NahidaWSState;
|
|
21
|
+
/** 订阅连接状态变化(插件据此做重连后的增量拉取判断)。返回取消订阅函数。 */
|
|
22
|
+
onStateChange(handler: (state: NahidaWSState) => void): () => void;
|
|
23
|
+
}
|