import { newOperationID } from './operationKey' // Client for the admin-only DingTalk scan-code session (系统设置 → 数据源配置). // The API proxies to the dingtalk-login sidecar; this module never sees the // token itself — only the base64 QR image and a terminal state. export type DingtalkSessionState = 'starting' | 'qr' | 'scanned' | 'reusing' | 'success' | 'expired' | 'failed' | 'closed' export interface DingtalkSessionView { id: string state: DingtalkSessionState created_at: number expires_at: number qr_png?: string error?: string } const sessionStates = new Set([ 'starting', 'qr', 'scanned', 'reusing', 'success', 'expired', 'failed', 'closed', ]) function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value) } export async function startDingtalkSession(space?: string): Promise { const response = await fetch('/api/v1/dingtalk-session', { method: 'POST', headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'X-Governance-Action': 'dingtalk-session', 'Idempotency-Key': newOperationID(), }, body: JSON.stringify(space ? { space } : {}), }) if (!response.ok) throw new Error(`发起钉钉扫码会话失败(HTTP ${response.status})`) return parseSession(await response.json()) } export async function fetchDingtalkSession(id: string, signal?: AbortSignal): Promise { const response = await fetch(`/api/v1/dingtalk-session/${encodeURIComponent(id)}`, { headers: { Accept: 'application/json' }, signal, }) if (!response.ok) throw new Error(`读取钉钉扫码会话失败(HTTP ${response.status})`) return parseSession(await response.json()) } export async function cancelDingtalkSession(id: string): Promise { await fetch(`/api/v1/dingtalk-session/${encodeURIComponent(id)}`, { method: 'DELETE', headers: { Accept: 'application/json' }, }).catch(() => undefined) } export interface RegisteredDingtalkSpace { connection_id: string name: string } export class DingtalkRequestError extends Error { constructor( message: string, public readonly code: string, public readonly status: number ) { super(message) this.name = 'DingtalkRequestError' } } // Register a DingTalk knowledge-base space (URL or bare space id) as a new // source connection. Errors carry the sidecar's machine codes so the UI can // explain them: login_required, space_not_found, name_conflict. export async function registerDingtalkSpace(url: string): Promise { const response = await fetch('/api/v1/dingtalk-spaces', { method: 'POST', headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'X-Governance-Action': 'dingtalk-space', 'Idempotency-Key': newOperationID(), }, body: JSON.stringify({ url }), }) if (!response.ok) { // 响应体只能读一次:错误码与后端 hint 一起取出(hint 优先,它比本地文案更具体)。 let code = '' let hint = '' try { const parsed = (await response.json()) as unknown if (isRecord(parsed)) { if (typeof parsed.error === 'string') code = parsed.error if (typeof parsed.hint === 'string') hint = parsed.hint } } catch { /* status-only */ } const friendly: Record = { login_required: '钉钉扫码会话无效或已过期,请先在钉钉来源卡片上「扫码刷新会话」', space_not_found: '未找到该知识库空间:请确认空间链接正确且当前账号有阅读权限', name_conflict: '该空间与已登记的来源同名', // 登记冲突分两种:同名来源还在用 vs 同一个登记键指向了别的空间。原因要说清, // 否则用户只能看到一个无细节的 409(2026-10-14 线上就是这样卡住的)。 space_name_conflict: '已有同名来源仍在使用(未下架):先在该来源卡片上「去掉来源」,或确认选的是同一个知识库空间', space_identity_conflict: '这个登记键已指向另一个知识库空间:刷新列表后重试;仍失败就把该来源「去掉来源」再登记', space_registration_failed: '登记失败(服务端内部错误):已记录,请稍后重试或让管理员看服务日志', invalid_space_url: '链接不是有效的钉钉知识库空间地址(应形如 alidocs.dingtalk.com/i/spaces/…)', } throw new DingtalkRequestError( hint || friendly[code] || `登记钉钉知识库失败(HTTP ${response.status}${code ? ':' + code : ''})`, code, response.status ) } const value = (await response.json()) as unknown if (!isRecord(value) || !isRecord(value.data)) throw new Error('invalid dingtalk space response') const data = value.data if (typeof data.connection_id !== 'string' || typeof data.name !== 'string') throw new Error('invalid dingtalk space response') return { connection_id: data.connection_id, name: data.name } } function parseSession(value: unknown): DingtalkSessionView { if ( !isRecord(value) || typeof value.id !== 'string' || typeof value.state !== 'string' || !sessionStates.has(value.state) ) { throw new Error('invalid dingtalk session response') } return { id: value.id, state: value.state as DingtalkSessionState, created_at: typeof value.created_at === 'number' ? value.created_at : 0, expires_at: typeof value.expires_at === 'number' ? value.expires_at : 0, qr_png: typeof value.qr_png === 'string' ? value.qr_png : undefined, error: typeof value.error === 'string' ? value.error : undefined, } }