@kimposoft/plugin-sdk 0.0.0-stage → 1.1.0-tp.20
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 +141 -4
- package/src/action-designer.ts +250 -0
- package/src/attachment-url.ts +195 -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 +250 -0
- package/src/editor-frame.ts +623 -0
- package/src/editor-session.ts +1214 -0
- package/src/editor-testing.ts +838 -0
- package/src/editor.ts +1641 -0
- package/src/frame-transport.ts +491 -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 +118 -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 +404 -0
- package/src/print.ts +393 -0
- package/src/surface.ts +281 -0
- package/src/theme-mocks.ts +140 -0
- package/src/theme.ts +125 -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 +16 -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 +250 -0
- package/src/ui.ts +479 -0
- package/src/workflow-designer.ts +475 -0
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
// 组织架构取人前端契约(IM 前端插件等使用)。
|
|
2
|
+
//
|
|
3
|
+
// 定位:IM 的"通讯录" = 组织架构树(不是好友列表),插件要渲染部门树 + 成员,
|
|
4
|
+
// 但**插件不碰组织表**——本契约只是对宿主既有 IAM 接口(org-units/tree、
|
|
5
|
+
// org-units/{id}/users、directory/users 等)的薄封装类型定义,真正的查询/鉴权仍在宿主,
|
|
6
|
+
// 插件侧不重新实现任何组织查询逻辑。
|
|
7
|
+
//
|
|
8
|
+
// 与 page.ts 的 PageRecordListClient 同一惯例:本文件只定义类型契约(Host 实现、经
|
|
9
|
+
// hostBridge/props 注入给插件),本身不构成安全边界——列表能拿到哪些部门/成员仍由宿主
|
|
10
|
+
// 后端裁决(如权限框架的数据范围),插件只管调用。
|
|
11
|
+
|
|
12
|
+
/** 部门树节点(对照宿主 OrgUnitNode 类型,仅摘取 IM 通讯录渲染需要的字段)。 */
|
|
13
|
+
export interface OrgDept {
|
|
14
|
+
id: string;
|
|
15
|
+
parentId: string | null;
|
|
16
|
+
name: string;
|
|
17
|
+
/** 物化路径(形如 "1/3/7"),供前端就地判断层级关系,不代表可以据此自行展开子部门。 */
|
|
18
|
+
path: string;
|
|
19
|
+
/** 子部门数(渲染展开箭头用;listDepartments 是 lazy 分层拉取,不代表本节点已含子节点数据)。 */
|
|
20
|
+
childCount?: number;
|
|
21
|
+
/** 部门直属成员数(渲染角标用)。 */
|
|
22
|
+
memberCount?: number;
|
|
23
|
+
/** active 可选取;inactive 仅供历史值解析为“已停用”展示。 */
|
|
24
|
+
statusCode?: string;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** 部门成员(对照宿主 DirectoryUser 类型的精简视图)。 */
|
|
28
|
+
export interface OrgMember {
|
|
29
|
+
userId: string;
|
|
30
|
+
userNo?: string;
|
|
31
|
+
loginName?: string;
|
|
32
|
+
displayName: string;
|
|
33
|
+
/** 受宿主会话保护、可直接交给 img.src 的头像地址。 */
|
|
34
|
+
avatar?: string;
|
|
35
|
+
mobile?: string;
|
|
36
|
+
email?: string;
|
|
37
|
+
/** 该用户的主部门 id;无主部门(理论上不应发生)时为 null。 */
|
|
38
|
+
primaryOrgUnitId?: string | null;
|
|
39
|
+
/** 用户的全部明确部门归属;同一用户可在多个部门节点出现。 */
|
|
40
|
+
memberships: readonly OrgMembership[];
|
|
41
|
+
statusCode?: string;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** 用户在一个明确部门的归属。全局搜索以 userId 去重,展示此数组而非丢弃兼任部门。 */
|
|
45
|
+
export interface OrgMembership {
|
|
46
|
+
readonly orgUnitId: string;
|
|
47
|
+
readonly orgUnitName?: string;
|
|
48
|
+
readonly primary: boolean;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* 组织架构取人客户端(hostBridge['org-directory'],IM 插件通讯录面板用)。
|
|
53
|
+
*
|
|
54
|
+
* 🔴 `listMembers` 只返回目标部门的**直属成员,不含子部门**——对应"部门群不含子部门"的
|
|
55
|
+
* 产品规则。宿主实现必须直接薄封装 `GET /api/v1/iam/org-units/{id}/users`
|
|
56
|
+
* (该端点本就只查直属成员),**不得自作主张递归**
|
|
57
|
+
* 拼出"含子部门"的语义。
|
|
58
|
+
*/
|
|
59
|
+
export interface OrgDirectoryClient {
|
|
60
|
+
/** 拉组织树(部门层级)。lazy:只拉 parentId 这一层,展开时再拉子层;parentId 缺省=拉根部门。 */
|
|
61
|
+
listDepartments(parentId?: string): Promise<OrgDept[]>;
|
|
62
|
+
/** 拉某部门的直属成员(⚠️ 不含子部门——见上方接口注释)。 */
|
|
63
|
+
listMembers(deptId: string, options?: { readonly includeChildren?: false }): Promise<OrgMember[]>;
|
|
64
|
+
/** 按名字/拼音搜人(IM 的"搜联系人"用);结果必须按 userId 去重,memberships 保留全部部门。 */
|
|
65
|
+
searchUsers(keyword: string, limit?: number): Promise<OrgMember[]>;
|
|
66
|
+
/**
|
|
67
|
+
* 按稳定 userId 批量解析当前可见实体。未返回的 id 表示已删除或超出当前数据权限,
|
|
68
|
+
* 调用方必须保留原 id 并显示悬空态,不得把它静默清空。
|
|
69
|
+
*/
|
|
70
|
+
resolveUsers?(userIds: readonly string[]): Promise<OrgMember[]>;
|
|
71
|
+
/**
|
|
72
|
+
* 按稳定部门 id 批量解析当前可见实体。inactive 部门仍可返回供历史值展示,
|
|
73
|
+
* 但不得作为新选择候选;未返回的 id 由调用方显示悬空态。
|
|
74
|
+
*/
|
|
75
|
+
resolveDepartments?(deptIds: readonly string[]): Promise<OrgDept[]>;
|
|
76
|
+
/** 当前用户自己的信息(IM 面板展示"我"这一行)。 */
|
|
77
|
+
me(): Promise<OrgMember>;
|
|
78
|
+
}
|