@opendikw/web-client 0.1.0-rc.1

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.
Files changed (57) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +31 -0
  3. package/dist/agent/agentClient.d.ts +26 -0
  4. package/dist/agent/agentClient.js +112 -0
  5. package/dist/agent/index.d.ts +1 -0
  6. package/dist/agent/index.js +1 -0
  7. package/dist/connection/index.d.ts +1 -0
  8. package/dist/connection/index.js +1 -0
  9. package/dist/convert/index.d.ts +1 -0
  10. package/dist/convert/index.js +1 -0
  11. package/dist/convert/mineru-convert.d.ts +83 -0
  12. package/dist/convert/mineru-convert.js +565 -0
  13. package/dist/core/client.d.ts +94 -0
  14. package/dist/core/client.js +386 -0
  15. package/dist/core/index.d.ts +2 -0
  16. package/dist/core/index.js +2 -0
  17. package/dist/core/ndjson.d.ts +9 -0
  18. package/dist/core/ndjson.js +57 -0
  19. package/dist/document/format.d.ts +17 -0
  20. package/dist/document/format.js +100 -0
  21. package/dist/document/index.d.ts +5 -0
  22. package/dist/document/index.js +5 -0
  23. package/dist/document/lang.d.ts +5 -0
  24. package/dist/document/lang.js +15 -0
  25. package/dist/document/markdown-blocks.d.ts +8 -0
  26. package/dist/document/markdown-blocks.js +169 -0
  27. package/dist/document/markdown.d.ts +32 -0
  28. package/dist/document/markdown.js +199 -0
  29. package/dist/document/source-inline-refs.d.ts +35 -0
  30. package/dist/document/source-inline-refs.js +242 -0
  31. package/dist/import/frontmatter-merge.d.ts +5 -0
  32. package/dist/import/frontmatter-merge.js +89 -0
  33. package/dist/import/import-bundle.d.ts +90 -0
  34. package/dist/import/import-bundle.js +336 -0
  35. package/dist/import/index.d.ts +5 -0
  36. package/dist/import/index.js +5 -0
  37. package/dist/import/kebab-source-name.d.ts +5 -0
  38. package/dist/import/kebab-source-name.js +31 -0
  39. package/dist/import/md-asset-refs.d.ts +27 -0
  40. package/dist/import/md-asset-refs.js +97 -0
  41. package/dist/import/tar-reader.d.ts +9 -0
  42. package/dist/import/tar-reader.js +114 -0
  43. package/dist/import/tar.d.ts +8 -0
  44. package/dist/import/tar.js +104 -0
  45. package/dist/translate/index.d.ts +1 -0
  46. package/dist/translate/index.js +1 -0
  47. package/dist/translate/translate.d.ts +69 -0
  48. package/dist/translate/translate.js +437 -0
  49. package/dist/types/agent.d.ts +82 -0
  50. package/dist/types/agent.js +1 -0
  51. package/dist/types/auth.d.ts +15 -0
  52. package/dist/types/auth.js +1 -0
  53. package/dist/types/index.d.ts +388 -0
  54. package/dist/types/index.js +3 -0
  55. package/dist/types/trace.d.ts +27 -0
  56. package/dist/types/trace.js +7 -0
  57. package/package.json +60 -0
@@ -0,0 +1,437 @@
1
+ // Browser-side wrapper around the /web/translate endpoint (job + poll, mirroring
2
+ // src/utils/mineru-convert.ts). Translates a document's markdown blocks to a
3
+ // target language and returns the translations aligned 1:1 with the input.
4
+ //
5
+ // Idempotency: IndexedDB keyed by sha256(targetLang + blocks). Same source +
6
+ // language → cache hit, no network. translateVersion gates invalidation.
7
+ import { sha256HexString } from "../import/import-bundle.js";
8
+ import { CACHE_TTL_MS, isCacheEntryExpired } from "../convert/mineru-convert.js";
9
+ // Bump when the translation logic changes in a way that makes previously-cached
10
+ // results wrong (the key embeds this, so old entries miss and re-translate).
11
+ // v2: server-side repair of untranslated / oversized / bilingual-echo blocks.
12
+ const TRANSLATE_VERSION = 2;
13
+ const DB_NAME = "dikw-translate-cache";
14
+ const DB_STORE = "entries";
15
+ const DB_VERSION = 1;
16
+ const POLL_INTERVAL_MS = 1200;
17
+ const POLL_MAX_FAILURES = 8;
18
+ const POLL_RETRY_CAP_MS = 15000;
19
+ function pollRetryDelayMs(attempt, baseMs) {
20
+ return Math.min(baseMs * 2 ** (attempt - 1), POLL_RETRY_CAP_MS);
21
+ }
22
+ export class TranslateError extends Error {
23
+ code;
24
+ constructor(code, message) {
25
+ super(message);
26
+ this.name = "TranslateError";
27
+ this.code = code;
28
+ }
29
+ }
30
+ /** Translate `blocks` into `targetLang`. Returns translations aligned 1:1 with
31
+ * the input order. Throws TranslateError on failure / abort. */
32
+ export async function translateBlocks(blocks, opts = {}) {
33
+ const signal = opts.signal;
34
+ const fetchFn = opts.fetch ?? fetch;
35
+ const targetLang = opts.targetLang ?? "zh";
36
+ const pollIntervalMs = opts.pollIntervalMs ?? POLL_INTERVAL_MS;
37
+ throwIfAborted(signal);
38
+ if (blocks.length === 0)
39
+ return [];
40
+ opts.onProgress?.({ phase: "hashing" });
41
+ const key = await cacheKey(blocks, targetLang);
42
+ throwIfAborted(signal);
43
+ if (opts.cache && !opts.refresh) {
44
+ const hit = await opts.cache.get(key);
45
+ if (hit && hit.length === blocks.length) {
46
+ opts.onProgress?.({ phase: "cache_hit" });
47
+ return hit;
48
+ }
49
+ }
50
+ opts.onProgress?.({ phase: "submitting" });
51
+ const jobId = await submitJob(blocks, targetLang, signal, fetchFn);
52
+ opts.onProgress?.({ phase: "polling" });
53
+ await pollUntilTerminal(jobId, signal, fetchFn, pollIntervalMs, opts.onProgress);
54
+ const response = await fetchResult(jobId, signal, fetchFn, pollIntervalMs);
55
+ if (response.status >= 400) {
56
+ const body = await safeJson(response);
57
+ throw new TranslateError(pickErrorCode(body, response.status), serverErrorMessage(body) ?? `translate result HTTP ${response.status}`);
58
+ }
59
+ const body = await safeJson(response);
60
+ const translations = alignBlocks(body, blocks.length);
61
+ if (opts.cache) {
62
+ try {
63
+ await opts.cache.put(key, translations);
64
+ }
65
+ catch {
66
+ // Cache write failure shouldn't block the result.
67
+ }
68
+ }
69
+ return translations;
70
+ }
71
+ /** GET /web/translate/health → whether the sidecar has a translator key. The
72
+ * reader hides the AI 翻译 entry when this is false. Any failure → false. */
73
+ export async function fetchTranslateEnabled(fetchFn = fetch) {
74
+ try {
75
+ const response = await fetchFn("/web/translate/health", { method: "GET" });
76
+ if (!response.ok)
77
+ return false;
78
+ const body = await safeJson(response);
79
+ return Boolean(body?.enabled);
80
+ }
81
+ catch {
82
+ return false;
83
+ }
84
+ }
85
+ function alignBlocks(body, expected) {
86
+ const raw = body?.blocks;
87
+ if (!Array.isArray(raw)) {
88
+ throw new TranslateError("invalid_response", "translate result missing blocks array");
89
+ }
90
+ const out = new Array(expected).fill("");
91
+ for (const item of raw) {
92
+ if (item && typeof item === "object" && "i" in item && "tr" in item) {
93
+ const i = item.i;
94
+ const tr = item.tr;
95
+ if (typeof i === "number" && i >= 0 && i < expected && typeof tr === "string") {
96
+ out[i] = tr;
97
+ }
98
+ }
99
+ }
100
+ return out;
101
+ }
102
+ async function cacheKey(blocks, targetLang) {
103
+ // Join on NUL: it can't appear in markdown source, so distinct block arrays
104
+ // can't collide into one key (a space separator would: ["a b","c"] and
105
+ // ["a","b c"] both flatten to "a b c", and the length guard wouldn't catch it).
106
+ return sha256HexString(`${TRANSLATE_VERSION}\n${targetLang}\n${blocks.join("\u0000")}`);
107
+ }
108
+ // ------------------------------------------------- job submit / poll / result
109
+ function jobUrl(jobId) {
110
+ return `/web/translate/jobs/${encodeURIComponent(jobId)}`;
111
+ }
112
+ async function submitJob(blocks, targetLang, signal, fetchFn) {
113
+ let response;
114
+ try {
115
+ response = await fetchFn("/web/translate/submit", {
116
+ method: "POST",
117
+ headers: { "Content-Type": "application/json" },
118
+ body: JSON.stringify({ blocks, targetLang }),
119
+ signal,
120
+ });
121
+ }
122
+ catch (err) {
123
+ if (signal?.aborted)
124
+ throw new TranslateError("aborted", "aborted");
125
+ throw new TranslateError("translator_api", err instanceof Error ? err.message : String(err));
126
+ }
127
+ if (response.status >= 400) {
128
+ const body = await safeJson(response);
129
+ throw new TranslateError(pickErrorCode(body, response.status), serverErrorMessage(body) ?? `translate submit HTTP ${response.status}`);
130
+ }
131
+ const body = await safeJson(response);
132
+ const jobId = body && typeof body === "object" && "jobId" in body
133
+ ? body.jobId
134
+ : undefined;
135
+ if (typeof jobId !== "string" || !jobId) {
136
+ throw new TranslateError("invalid_response", "translate submit response missing jobId");
137
+ }
138
+ return jobId;
139
+ }
140
+ async function pollUntilTerminal(jobId, signal, fetchFn, pollIntervalMs, onProgress) {
141
+ let failures = 0;
142
+ let lastPartialCount = 0;
143
+ try {
144
+ while (true) {
145
+ throwIfAborted(signal);
146
+ let response;
147
+ try {
148
+ response = await fetchFn(jobUrl(jobId), { method: "GET", signal });
149
+ }
150
+ catch (err) {
151
+ if (signal?.aborted)
152
+ throw new TranslateError("aborted", "aborted");
153
+ if (++failures > POLL_MAX_FAILURES) {
154
+ throw new TranslateError("translator_api", err instanceof Error ? err.message : String(err));
155
+ }
156
+ await delay(pollRetryDelayMs(failures, pollIntervalMs), signal);
157
+ continue;
158
+ }
159
+ if (response.status === 404) {
160
+ throw new TranslateError("translator_api", "translation job not found (the server may have restarted or evicted it)");
161
+ }
162
+ if (response.status >= 500) {
163
+ if (++failures > POLL_MAX_FAILURES) {
164
+ throw new TranslateError("translator_api", `translate job poll HTTP ${response.status}`);
165
+ }
166
+ await delay(pollRetryDelayMs(failures, pollIntervalMs), signal);
167
+ continue;
168
+ }
169
+ if (response.status >= 400) {
170
+ const body = await safeJson(response);
171
+ throw new TranslateError(pickErrorCode(body, response.status), serverErrorMessage(body) ?? `translate job poll HTTP ${response.status}`);
172
+ }
173
+ failures = 0;
174
+ const body = await safeJson(response);
175
+ const partial = partialBlocksOf(body);
176
+ // The server republishes the same growing array on every poll; only surface
177
+ // a partial when new blocks have actually landed, so the dual column isn't
178
+ // re-rendered (every block, both columns) on each poll interval.
179
+ if (partial.length > lastPartialCount) {
180
+ lastPartialCount = partial.length;
181
+ onProgress?.({ phase: "partial", blocks: partial });
182
+ }
183
+ const status = jobStatusOf(body);
184
+ if (status === "succeeded")
185
+ return;
186
+ if (status === "failed") {
187
+ throw new TranslateError(pickErrorCode(body, 200), serverErrorMessage(body) ?? "translation failed");
188
+ }
189
+ await delay(pollIntervalMs, signal);
190
+ }
191
+ }
192
+ catch (err) {
193
+ if (signal?.aborted || (err instanceof TranslateError && err.code === "aborted")) {
194
+ void cancelJob(jobId, fetchFn);
195
+ throw new TranslateError("aborted", "aborted");
196
+ }
197
+ throw err;
198
+ }
199
+ }
200
+ async function fetchResult(jobId, signal, fetchFn, pollIntervalMs) {
201
+ let failures = 0;
202
+ while (true) {
203
+ throwIfAborted(signal);
204
+ let response;
205
+ try {
206
+ response = await fetchFn(`${jobUrl(jobId)}/result`, { method: "GET", signal });
207
+ }
208
+ catch (err) {
209
+ if (signal?.aborted)
210
+ throw new TranslateError("aborted", "aborted");
211
+ if (++failures > POLL_MAX_FAILURES) {
212
+ throw new TranslateError("translator_api", err instanceof Error ? err.message : String(err));
213
+ }
214
+ await delay(pollRetryDelayMs(failures, pollIntervalMs), signal);
215
+ continue;
216
+ }
217
+ if (response.status >= 500) {
218
+ if (++failures > POLL_MAX_FAILURES) {
219
+ throw new TranslateError("translator_api", `translate result HTTP ${response.status}`);
220
+ }
221
+ await delay(pollRetryDelayMs(failures, pollIntervalMs), signal);
222
+ continue;
223
+ }
224
+ return response;
225
+ }
226
+ }
227
+ async function cancelJob(jobId, fetchFn) {
228
+ try {
229
+ await fetchFn(`${jobUrl(jobId)}/cancel`, { method: "POST" });
230
+ }
231
+ catch {
232
+ // best-effort
233
+ }
234
+ }
235
+ function jobStatusOf(body) {
236
+ if (body && typeof body === "object" && "status" in body) {
237
+ const s = body.status;
238
+ if (typeof s === "string")
239
+ return s;
240
+ }
241
+ return "";
242
+ }
243
+ /** Extract `progress.blocks` (the blocks translated so far) from a poll body,
244
+ * validating each `{ i, tr }` so a malformed payload never reaches the caller. */
245
+ function partialBlocksOf(body) {
246
+ const raw = body?.progress?.blocks;
247
+ if (!Array.isArray(raw))
248
+ return [];
249
+ const out = [];
250
+ for (const item of raw) {
251
+ if (item && typeof item === "object" && "i" in item && "tr" in item) {
252
+ const i = item.i;
253
+ const tr = item.tr;
254
+ if (typeof i === "number" && Number.isInteger(i) && i >= 0 && typeof tr === "string") {
255
+ out.push({ i, tr });
256
+ }
257
+ }
258
+ }
259
+ return out;
260
+ }
261
+ function serverErrorMessage(body) {
262
+ if (body && typeof body === "object" && "error" in body) {
263
+ const message = body.error?.message;
264
+ if (typeof message === "string")
265
+ return message;
266
+ }
267
+ return undefined;
268
+ }
269
+ const KNOWN_CODES = new Set([
270
+ "translator_auth",
271
+ "translator_rate_limit",
272
+ "translator_timeout",
273
+ "translator_api",
274
+ "translator_invalid_response",
275
+ "translator_input",
276
+ "translate_disabled",
277
+ ]);
278
+ function pickErrorCode(body, status) {
279
+ if (body && typeof body === "object" && "error" in body) {
280
+ const code = body.error?.code;
281
+ if (typeof code === "string" && KNOWN_CODES.has(code)) {
282
+ return code;
283
+ }
284
+ }
285
+ if (status === 503)
286
+ return "translate_disabled";
287
+ if (status === 401)
288
+ return "translator_auth";
289
+ if (status === 413)
290
+ return "translator_input";
291
+ if (status === 429)
292
+ return "translator_rate_limit";
293
+ if (status === 504)
294
+ return "translator_timeout";
295
+ return "translator_api";
296
+ }
297
+ function throwIfAborted(signal) {
298
+ if (signal?.aborted)
299
+ throw new TranslateError("aborted", "aborted");
300
+ }
301
+ async function safeJson(response) {
302
+ try {
303
+ return await response.json();
304
+ }
305
+ catch {
306
+ return null;
307
+ }
308
+ }
309
+ function delay(ms, signal) {
310
+ return new Promise((resolve, reject) => {
311
+ if (signal?.aborted) {
312
+ reject(new TranslateError("aborted", "aborted"));
313
+ return;
314
+ }
315
+ const onAbort = () => {
316
+ clearTimeout(timer);
317
+ reject(new TranslateError("aborted", "aborted"));
318
+ };
319
+ const timer = setTimeout(() => {
320
+ signal?.removeEventListener("abort", onAbort);
321
+ resolve();
322
+ }, ms);
323
+ signal?.addEventListener("abort", onAbort, { once: true });
324
+ });
325
+ }
326
+ // ----------------------------------------------------------- IndexedDB cache
327
+ /** In-memory cache; fallback for jsdom and a deterministic test shim. */
328
+ export class MemoryTranslateCache {
329
+ store = new Map();
330
+ async get(key) {
331
+ return this.store.get(key) ?? null;
332
+ }
333
+ async put(key, value) {
334
+ this.store.set(key, value);
335
+ }
336
+ }
337
+ /** IndexedDB-backed cache. Returns null when IndexedDB is unavailable (jsdom). */
338
+ export function tryOpenDefaultTranslateCache(options) {
339
+ if (typeof indexedDB === "undefined") {
340
+ return Promise.resolve(null);
341
+ }
342
+ return new Promise((resolve) => {
343
+ const name = options?.namespace ? `${DB_NAME}:${options.namespace}` : DB_NAME;
344
+ const req = indexedDB.open(name, DB_VERSION);
345
+ req.onupgradeneeded = () => {
346
+ const db = req.result;
347
+ if (!db.objectStoreNames.contains(DB_STORE)) {
348
+ db.createObjectStore(DB_STORE);
349
+ }
350
+ };
351
+ req.onsuccess = () => {
352
+ const cache = new IDBTranslateCache(req.result);
353
+ scheduleIdleSweep(cache);
354
+ resolve(cache);
355
+ };
356
+ req.onerror = () => resolve(null);
357
+ });
358
+ }
359
+ function scheduleIdleSweep(cache) {
360
+ const run = () => {
361
+ void cache.sweepExpired().catch(() => { });
362
+ };
363
+ const ric = globalThis.requestIdleCallback;
364
+ if (typeof ric === "function") {
365
+ ric(run, { timeout: 10000 });
366
+ }
367
+ else {
368
+ setTimeout(run, 0);
369
+ }
370
+ }
371
+ export class IDBTranslateCache {
372
+ db;
373
+ constructor(db) {
374
+ this.db = db;
375
+ }
376
+ /** Delete entries older than CACHE_TTL_MS via a readwrite cursor. Resolves on
377
+ * transaction commit; rejects on error so the caller can swallow it. */
378
+ sweepExpired(now = Date.now()) {
379
+ return new Promise((resolve, reject) => {
380
+ let tx;
381
+ try {
382
+ tx = this.db.transaction(DB_STORE, "readwrite");
383
+ }
384
+ catch (err) {
385
+ reject(err);
386
+ return;
387
+ }
388
+ tx.oncomplete = () => resolve();
389
+ tx.onabort = () => reject(tx.error ?? new Error("sweepExpired transaction aborted"));
390
+ tx.onerror = () => reject(tx.error);
391
+ const req = tx.objectStore(DB_STORE).openCursor();
392
+ req.onsuccess = () => {
393
+ const cursor = req.result;
394
+ if (!cursor)
395
+ return;
396
+ const record = cursor.value;
397
+ if (isCacheEntryExpired(record?.cachedAt, now, CACHE_TTL_MS)) {
398
+ cursor.delete();
399
+ }
400
+ cursor.continue();
401
+ };
402
+ req.onerror = () => reject(req.error);
403
+ });
404
+ }
405
+ async get(key) {
406
+ const record = await this.txGet(key);
407
+ if (!record || record.translateVersion !== TRANSLATE_VERSION)
408
+ return null;
409
+ if (isCacheEntryExpired(record.cachedAt, Date.now(), CACHE_TTL_MS))
410
+ return null;
411
+ return record.translations;
412
+ }
413
+ async put(key, value) {
414
+ const record = {
415
+ translateVersion: TRANSLATE_VERSION,
416
+ translations: value,
417
+ cachedAt: Date.now(),
418
+ };
419
+ await this.txPut(key, record);
420
+ }
421
+ txGet(key) {
422
+ return new Promise((resolve, reject) => {
423
+ const tx = this.db.transaction(DB_STORE, "readonly");
424
+ const req = tx.objectStore(DB_STORE).get(key);
425
+ req.onsuccess = () => resolve(req.result);
426
+ req.onerror = () => reject(req.error);
427
+ });
428
+ }
429
+ txPut(key, value) {
430
+ return new Promise((resolve, reject) => {
431
+ const tx = this.db.transaction(DB_STORE, "readwrite");
432
+ const req = tx.objectStore(DB_STORE).put(value, key);
433
+ req.onsuccess = () => resolve();
434
+ req.onerror = () => reject(req.error);
435
+ });
436
+ }
437
+ }
@@ -0,0 +1,82 @@
1
+ import type { Layer } from "./index.js";
2
+ export type AgentMessageRole = "user" | "assistant";
3
+ export type AgentProposalStatus = "pending" | "confirmed" | "rejected" | "running" | "succeeded" | "failed";
4
+ export type AgentMaintenanceAction = "ingest" | "synth" | "lint_propose";
5
+ export interface AgentMessage {
6
+ id: string;
7
+ role: AgentMessageRole;
8
+ content: string;
9
+ createdAt: string;
10
+ }
11
+ export type AgentSourceKind = "core" | "web";
12
+ export interface AgentSource {
13
+ path: string;
14
+ title?: string | null;
15
+ layer?: Layer | string | null;
16
+ excerpt?: string | null;
17
+ score?: number | null;
18
+ kind?: AgentSourceKind;
19
+ }
20
+ export interface AgentToolEvent {
21
+ id: string;
22
+ type: "tool_call";
23
+ name: string;
24
+ status: "running" | "succeeded" | "failed";
25
+ createdAt: string;
26
+ input?: unknown;
27
+ output?: unknown;
28
+ error?: string;
29
+ }
30
+ export interface AgentProposal {
31
+ id: string;
32
+ action: AgentMaintenanceAction;
33
+ title: string;
34
+ description: string;
35
+ status: AgentProposalStatus;
36
+ params?: Record<string, unknown>;
37
+ taskId?: string;
38
+ createdAt: string;
39
+ updatedAt: string;
40
+ }
41
+ export interface SessionSummary {
42
+ id: string;
43
+ title: string;
44
+ createdAt: string;
45
+ updatedAt: string;
46
+ messageCount: number;
47
+ lastMessagePreview: string;
48
+ }
49
+ export interface AgentSession extends SessionSummary {
50
+ messages: AgentMessage[];
51
+ toolEvents: AgentToolEvent[];
52
+ sources: AgentSource[];
53
+ proposals: AgentProposal[];
54
+ }
55
+ export type AgentStreamEvent = {
56
+ type: "agent_start";
57
+ sessionId: string;
58
+ } | {
59
+ type: "message_delta";
60
+ sessionId: string;
61
+ delta: string;
62
+ } | {
63
+ type: "tool_event";
64
+ sessionId: string;
65
+ event: AgentToolEvent;
66
+ } | {
67
+ type: "source";
68
+ sessionId: string;
69
+ source: AgentSource;
70
+ } | {
71
+ type: "proposal";
72
+ sessionId: string;
73
+ proposal: AgentProposal;
74
+ } | {
75
+ type: "error";
76
+ sessionId: string;
77
+ code: string;
78
+ message: string;
79
+ } | {
80
+ type: "agent_end";
81
+ sessionId: string;
82
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,15 @@
1
+ export type AuthRole = "viewer" | "editor";
2
+ export interface AuthUser {
3
+ sub: string;
4
+ name?: string;
5
+ email?: string;
6
+ }
7
+ export type AuthState = {
8
+ enabled: false;
9
+ } | {
10
+ enabled: true;
11
+ user: AuthUser;
12
+ role: AuthRole;
13
+ issuer?: string;
14
+ coreId?: string;
15
+ };
@@ -0,0 +1 @@
1
+ export {};