@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,565 @@
1
+ // Browser-side wrapper around the /web/mineru/convert endpoint.
2
+ //
3
+ // Public surface:
4
+ // * convertSource(file) — POST file to sidecar, get back markdown + assets.
5
+ // Skips network on IndexedDB cache hit.
6
+ // * convertedToFiles(c) — materialize ConvertedSource into File[] that
7
+ // buildImportBundle's scanFiles strips correctly
8
+ // (webkitRelativePath="_mineru/<stem>/...").
9
+ //
10
+ // Idempotency layer (b) in the plan: IndexedDB keyed by sha256(input). Same
11
+ // file content → same cache key, regardless of filename. mineruVersion gates
12
+ // invalidation when the rewrite logic changes.
13
+ import { sha256Hex } from "../import/import-bundle.js";
14
+ import { kebabStem } from "../import/kebab-source-name.js";
15
+ import { readTar, TarReaderError } from "../import/tar-reader.js";
16
+ export const MINERU_EXTENSIONS = new Set([
17
+ ".pdf",
18
+ ".doc",
19
+ ".docx",
20
+ ".ppt",
21
+ ".pptx",
22
+ ".xls",
23
+ ".xlsx",
24
+ ]);
25
+ // Bumped to 2 when the sidecar frontmatter changed from a nested ``source: {…}``
26
+ // block to flat keys (ADR 0004): cache entries hold the converted markdown
27
+ // *including* that frontmatter, so stale entries must be invalidated.
28
+ const MINERU_VERSION = 2;
29
+ const DB_NAME = "dikw-mineru-cache";
30
+ const DB_STORE = "entries";
31
+ const DB_VERSION = 1;
32
+ /** Cached conversions are retained for 7 days from their write time, then
33
+ * swept on the next time the cache is opened (issue: IndexedDB cache growth).
34
+ * Absolute TTL — a cache hit does not refresh ``cachedAt``. */
35
+ export const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
36
+ // Browser-driven poll cadence for the detached conversion job. Each poll is a
37
+ // short, independent request (issue #60) — no held connection, so there's
38
+ // nothing for a reverse proxy to time out; the sidecar's 10-min budget stays
39
+ // the authoritative ceiling. POLL_MAX_FAILURES bounds transient-error retries.
40
+ const POLL_INTERVAL_MS = 1500;
41
+ const POLL_MAX_FAILURES = 8;
42
+ const POLL_RETRY_CAP_MS = 15000;
43
+ /** Capped exponential backoff for transient poll/result failures, scaled off
44
+ * the poll interval (so tests with a tiny interval stay fast). Mirrors the
45
+ * reconnect backoff DikwClient.streamTaskEvents uses for the same flaky-proxy
46
+ * reason (#56), so a longer tunnel blip doesn't abort a still-running job. */
47
+ function pollRetryDelayMs(attempt, baseMs) {
48
+ return Math.min(baseMs * 2 ** (attempt - 1), POLL_RETRY_CAP_MS);
49
+ }
50
+ export class MineruConvertError extends Error {
51
+ code;
52
+ constructor(code, message) {
53
+ super(message);
54
+ this.name = "MineruConvertError";
55
+ this.code = code;
56
+ }
57
+ }
58
+ export async function convertSource(file, opts = {}) {
59
+ const signal = opts.signal;
60
+ const fetchFn = opts.fetch ?? fetch;
61
+ signalThrowIfAborted(signal);
62
+ opts.onProgress?.({ phase: "hashing" });
63
+ const buf = await file.arrayBuffer();
64
+ const inputSha = await sha256Hex(buf);
65
+ signalThrowIfAborted(signal);
66
+ if (opts.cache) {
67
+ const hit = await opts.cache.get(inputSha);
68
+ if (hit) {
69
+ opts.onProgress?.({ phase: "cache_hit" });
70
+ return hit;
71
+ }
72
+ }
73
+ opts.onProgress?.({ phase: "uploading" });
74
+ const fd = new FormData();
75
+ fd.append("file", file);
76
+ let submitUrl = `/web/mineru/convert?inputSha=${encodeURIComponent(inputSha)}`;
77
+ if (opts.originalFilename) {
78
+ submitUrl += `&originalFilename=${encodeURIComponent(opts.originalFilename)}`;
79
+ }
80
+ // Submit returns a job id immediately; the conversion then runs detached on
81
+ // the sidecar. Polling and the result fetch are each short, independent
82
+ // requests, so no single request approaches a reverse-proxy timeout (#60).
83
+ const jobId = await submitJob(submitUrl, fd, signal, fetchFn);
84
+ opts.onProgress?.({ phase: "polling" });
85
+ await pollUntilTerminal(jobId, signal, fetchFn, opts.pollIntervalMs ?? POLL_INTERVAL_MS);
86
+ opts.onProgress?.({ phase: "downloading" });
87
+ const response = await fetchResult(jobId, signal, fetchFn, opts.pollIntervalMs ?? POLL_INTERVAL_MS);
88
+ if (response.status >= 400) {
89
+ const body = await safeJson(response);
90
+ throw new MineruConvertError(pickErrorCode(body, response.status), serverErrorMessage(body) ?? `mineru result HTTP ${response.status}`);
91
+ }
92
+ const ct = response.headers.get("content-type") ?? "";
93
+ if (!ct.toLowerCase().includes("application/x-tar+gzip")) {
94
+ throw new MineruConvertError("invalid_response", `unexpected content-type ${JSON.stringify(ct)}`);
95
+ }
96
+ const gzBytes = new Uint8Array(await response.arrayBuffer());
97
+ signalThrowIfAborted(signal);
98
+ let tarBytes;
99
+ try {
100
+ tarBytes = await gunzipBytes(gzBytes);
101
+ }
102
+ catch (err) {
103
+ throw new MineruConvertError("invalid_response", `failed to gunzip response: ${err instanceof Error ? err.message : String(err)}`);
104
+ }
105
+ let entries;
106
+ try {
107
+ entries = readTar(tarBytes);
108
+ }
109
+ catch (err) {
110
+ if (err instanceof TarReaderError) {
111
+ throw new MineruConvertError("invalid_response", `bad tar: ${err.message}`);
112
+ }
113
+ throw err;
114
+ }
115
+ const stem = stemOf(file.name);
116
+ const mdName = `${stem}.md`;
117
+ let markdown = null;
118
+ const assets = new Map();
119
+ for (const entry of entries) {
120
+ if (entry.archivePath === mdName) {
121
+ markdown = new TextDecoder("utf-8").decode(entry.data);
122
+ }
123
+ else if (entry.archivePath.startsWith("assets/")) {
124
+ assets.set(entry.archivePath, entry.data);
125
+ }
126
+ }
127
+ if (markdown === null) {
128
+ throw new MineruConvertError("invalid_response", `sidecar tar missing ${mdName}`);
129
+ }
130
+ const converted = {
131
+ input: file,
132
+ inputSha,
133
+ stem,
134
+ markdown,
135
+ assets,
136
+ };
137
+ if (opts.cache) {
138
+ try {
139
+ await opts.cache.put(inputSha, converted);
140
+ }
141
+ catch {
142
+ // Cache write failure shouldn't block the conversion result.
143
+ }
144
+ }
145
+ return converted;
146
+ }
147
+ export function convertedToFiles(c) {
148
+ // The synthetic root is the kebab stem (ADR 0004) — no inputSha suffix.
149
+ // ``kebabStem`` is idempotent on an already-kebab stem (the upload name is
150
+ // kebab'd upstream). Two converted inputs whose stems kebab to the same root
151
+ // therefore share this raw path; ``scanFiles`` drops the second as a visible
152
+ // ``duplicate_path`` skip (the accepted trade for dropping ``-sha12`` —
153
+ // ADR 0004 §3). ``normalizeForImport``'s ``-2``/``-3`` numbering only applies
154
+ // to distinct *plain* names that collapse to the same kebab.
155
+ const root = kebabStem(c.stem);
156
+ const files = [];
157
+ files.push(syntheticFile(`${root}.md`, `_mineru/${root}/${root}.md`, new TextEncoder().encode(c.markdown), "text/markdown"));
158
+ // Sort assets so iteration order doesn't perturb buildImportBundle's sha.
159
+ const keys = Array.from(c.assets.keys()).sort();
160
+ for (const archivePath of keys) {
161
+ const data = c.assets.get(archivePath);
162
+ const basename = archivePath.split("/").pop() ?? archivePath;
163
+ files.push(syntheticFile(basename, `_mineru/${root}/${archivePath}`, data));
164
+ }
165
+ return files;
166
+ }
167
+ function syntheticFile(name, webkitRelativePath, data, type) {
168
+ const buf = new ArrayBuffer(data.byteLength);
169
+ new Uint8Array(buf).set(data);
170
+ const file = new File([buf], name, type ? { type } : undefined);
171
+ Object.defineProperty(file, "webkitRelativePath", {
172
+ value: webkitRelativePath,
173
+ enumerable: true,
174
+ configurable: true,
175
+ writable: false,
176
+ });
177
+ return file;
178
+ }
179
+ function stemOf(fileName) {
180
+ const base = fileName.replace(/^.*[\\/]/, "");
181
+ const i = base.lastIndexOf(".");
182
+ const stem = i < 0 ? base : base.slice(0, i);
183
+ // Strip path / wikilink-breaking chars so the synthesized archive path
184
+ // doesn't accidentally split into multiple segments.
185
+ return stem.replace(/[\\/]/g, "_").replace(/[\]|]/g, "_") || "untitled";
186
+ }
187
+ function signalThrowIfAborted(signal) {
188
+ if (signal?.aborted) {
189
+ throw new MineruConvertError("aborted", "aborted");
190
+ }
191
+ }
192
+ async function safeJson(response) {
193
+ try {
194
+ return await response.json();
195
+ }
196
+ catch {
197
+ return null;
198
+ }
199
+ }
200
+ function pickErrorCode(body, status) {
201
+ if (body && typeof body === "object" && "error" in body) {
202
+ const code = body.error?.code;
203
+ if (typeof code === "string") {
204
+ if (code === "mineru_auth" ||
205
+ code === "mineru_input" ||
206
+ code === "mineru_quota" ||
207
+ code === "mineru_timeout" ||
208
+ code === "mineru_api" ||
209
+ code === "mineru_disabled") {
210
+ return code;
211
+ }
212
+ }
213
+ }
214
+ if (status === 503)
215
+ return "mineru_disabled";
216
+ if (status === 401)
217
+ return "mineru_auth";
218
+ if (status === 413)
219
+ return "mineru_input";
220
+ if (status === 429)
221
+ return "mineru_quota";
222
+ if (status === 504)
223
+ return "mineru_timeout";
224
+ return "mineru_api";
225
+ }
226
+ // --------------------------------------------- job submit / poll / result (#60)
227
+ function jobUrl(jobId) {
228
+ return `/web/mineru/jobs/${encodeURIComponent(jobId)}`;
229
+ }
230
+ /** POST the file, get back a job id. The conversion then runs detached on the
231
+ * sidecar — this request returns in seconds regardless of conversion time. */
232
+ async function submitJob(submitUrl, fd, signal, fetchFn) {
233
+ let response;
234
+ try {
235
+ response = await fetchFn(submitUrl, { method: "POST", body: fd, signal });
236
+ }
237
+ catch (err) {
238
+ if (signal?.aborted)
239
+ throw new MineruConvertError("aborted", "aborted");
240
+ throw new MineruConvertError("mineru_api", err instanceof Error ? err.message : String(err));
241
+ }
242
+ if (response.status >= 400) {
243
+ const body = await safeJson(response);
244
+ throw new MineruConvertError(pickErrorCode(body, response.status), serverErrorMessage(body) ?? `mineru convert HTTP ${response.status}`);
245
+ }
246
+ const body = await safeJson(response);
247
+ const jobId = body && typeof body === "object" && "jobId" in body
248
+ ? body.jobId
249
+ : undefined;
250
+ if (typeof jobId !== "string" || !jobId) {
251
+ throw new MineruConvertError("invalid_response", "mineru convert response missing jobId");
252
+ }
253
+ return jobId;
254
+ }
255
+ /** Poll GET /web/mineru/jobs/<id> until the job is terminal. Each poll is a
256
+ * short request; transient network/5xx failures retry up to POLL_MAX_FAILURES;
257
+ * a 404 (evicted job / restarted sidecar) is fatal. On abort, tells the sidecar
258
+ * to cancel (best-effort) and throws "aborted". */
259
+ async function pollUntilTerminal(jobId, signal, fetchFn, pollIntervalMs) {
260
+ let failures = 0;
261
+ try {
262
+ while (true) {
263
+ signalThrowIfAborted(signal);
264
+ let response;
265
+ try {
266
+ response = await fetchFn(jobUrl(jobId), { method: "GET", signal });
267
+ }
268
+ catch (err) {
269
+ if (signal?.aborted)
270
+ throw new MineruConvertError("aborted", "aborted");
271
+ if (++failures > POLL_MAX_FAILURES) {
272
+ throw new MineruConvertError("mineru_api", err instanceof Error ? err.message : String(err));
273
+ }
274
+ await convertDelay(pollRetryDelayMs(failures, pollIntervalMs), signal);
275
+ continue;
276
+ }
277
+ // 404 → job evicted / sidecar restarted: not transient, no result coming.
278
+ if (response.status === 404) {
279
+ throw new MineruConvertError("mineru_api", "conversion job not found (the server may have restarted or evicted it)");
280
+ }
281
+ if (response.status >= 500) {
282
+ if (++failures > POLL_MAX_FAILURES) {
283
+ throw new MineruConvertError("mineru_api", `mineru job poll HTTP ${response.status}`);
284
+ }
285
+ await convertDelay(pollRetryDelayMs(failures, pollIntervalMs), signal);
286
+ continue;
287
+ }
288
+ if (response.status >= 400) {
289
+ const body = await safeJson(response);
290
+ throw new MineruConvertError(pickErrorCode(body, response.status), serverErrorMessage(body) ?? `mineru job poll HTTP ${response.status}`);
291
+ }
292
+ failures = 0;
293
+ const body = await safeJson(response);
294
+ const status = jobStatusOf(body);
295
+ if (status === "succeeded")
296
+ return;
297
+ if (status === "failed") {
298
+ // Surface the same wire code the sidecar recorded (mineru_quota / …).
299
+ throw new MineruConvertError(pickErrorCode(body, 200), serverErrorMessage(body) ?? "mineru conversion failed");
300
+ }
301
+ // pending | running | unknown → keep polling.
302
+ await convertDelay(pollIntervalMs, signal);
303
+ }
304
+ }
305
+ catch (err) {
306
+ if (signal?.aborted || (err instanceof MineruConvertError && err.code === "aborted")) {
307
+ // Best-effort: tell the sidecar to stop the detached conversion. The UI
308
+ // already reflects the user's cancel intent, so swallow any failure.
309
+ void cancelJob(jobId, fetchFn);
310
+ throw new MineruConvertError("aborted", "aborted");
311
+ }
312
+ throw err;
313
+ }
314
+ }
315
+ /** Fetch the result tar.gz. Retries transient network/5xx failures (symmetric
316
+ * with the poll loop — the whole point of #60 is surviving a flaky transport,
317
+ * and the bytes are sitting ready on the sidecar). A 4xx (404 consumed/evicted,
318
+ * 409 not-ready) is returned to the caller without retry. */
319
+ async function fetchResult(jobId, signal, fetchFn, pollIntervalMs) {
320
+ let failures = 0;
321
+ while (true) {
322
+ signalThrowIfAborted(signal);
323
+ let response;
324
+ try {
325
+ response = await fetchFn(`${jobUrl(jobId)}/result`, { method: "GET", signal });
326
+ }
327
+ catch (err) {
328
+ if (signal?.aborted)
329
+ throw new MineruConvertError("aborted", "aborted");
330
+ if (++failures > POLL_MAX_FAILURES) {
331
+ throw new MineruConvertError("mineru_api", err instanceof Error ? err.message : String(err));
332
+ }
333
+ await convertDelay(pollRetryDelayMs(failures, pollIntervalMs), signal);
334
+ continue;
335
+ }
336
+ if (response.status >= 500) {
337
+ if (++failures > POLL_MAX_FAILURES) {
338
+ throw new MineruConvertError("mineru_api", `mineru result HTTP ${response.status}`);
339
+ }
340
+ await convertDelay(pollRetryDelayMs(failures, pollIntervalMs), signal);
341
+ continue;
342
+ }
343
+ return response;
344
+ }
345
+ }
346
+ async function cancelJob(jobId, fetchFn) {
347
+ try {
348
+ await fetchFn(`${jobUrl(jobId)}/cancel`, { method: "POST" });
349
+ }
350
+ catch {
351
+ // best-effort
352
+ }
353
+ }
354
+ function jobStatusOf(body) {
355
+ if (body && typeof body === "object" && "status" in body) {
356
+ const s = body.status;
357
+ if (typeof s === "string")
358
+ return s;
359
+ }
360
+ return "";
361
+ }
362
+ function serverErrorMessage(body) {
363
+ if (body && typeof body === "object" && "error" in body) {
364
+ const message = body.error?.message;
365
+ if (typeof message === "string")
366
+ return message;
367
+ }
368
+ return undefined;
369
+ }
370
+ /** setTimeout as a promise that rejects with an "aborted" MineruConvertError the
371
+ * moment the signal fires, so a cancel during the poll wait exits at once. */
372
+ function convertDelay(ms, signal) {
373
+ return new Promise((resolve, reject) => {
374
+ if (signal?.aborted) {
375
+ reject(new MineruConvertError("aborted", "aborted"));
376
+ return;
377
+ }
378
+ const onAbort = () => {
379
+ clearTimeout(timer);
380
+ reject(new MineruConvertError("aborted", "aborted"));
381
+ };
382
+ const timer = setTimeout(() => {
383
+ signal?.removeEventListener("abort", onAbort);
384
+ resolve();
385
+ }, ms);
386
+ signal?.addEventListener("abort", onAbort, { once: true });
387
+ });
388
+ }
389
+ async function gunzipBytes(bytes) {
390
+ if (typeof DecompressionStream === "undefined") {
391
+ throw new Error("DecompressionStream is not available in this environment");
392
+ }
393
+ const buf = new ArrayBuffer(bytes.byteLength);
394
+ new Uint8Array(buf).set(bytes);
395
+ const source = new Response(new Blob([buf])).body;
396
+ const inflated = source.pipeThrough(new DecompressionStream("gzip"));
397
+ return new Uint8Array(await new Response(inflated).arrayBuffer());
398
+ }
399
+ // ----------------------------------------------------------- IndexedDB cache
400
+ /** In-memory cache. Used as a fallback when IndexedDB is unavailable (jsdom)
401
+ * and as a deterministic shim for tests. */
402
+ export class MemoryConvertCache {
403
+ store = new Map();
404
+ async get(key) {
405
+ return this.store.get(key) ?? null;
406
+ }
407
+ async put(key, value) {
408
+ this.store.set(key, value);
409
+ }
410
+ }
411
+ /** IndexedDB-backed cache. Returns null when IndexedDB is not available
412
+ * (jsdom test env, very old browsers). Caller should treat ``null`` as
413
+ * "no cache" and proceed without bypass. */
414
+ export function tryOpenDefaultCache(options) {
415
+ if (typeof indexedDB === "undefined") {
416
+ return Promise.resolve(null);
417
+ }
418
+ return new Promise((resolve) => {
419
+ const name = options?.namespace ? `${DB_NAME}:${options.namespace}` : DB_NAME;
420
+ const req = indexedDB.open(name, DB_VERSION);
421
+ req.onupgradeneeded = () => {
422
+ const db = req.result;
423
+ if (!db.objectStoreNames.contains(DB_STORE)) {
424
+ db.createObjectStore(DB_STORE);
425
+ }
426
+ };
427
+ req.onsuccess = () => {
428
+ const cache = new IDBConvertCache(req.result);
429
+ // Best-effort prune of entries older than CACHE_TTL_MS, deferred to idle.
430
+ // The sweep takes a readwrite lock on the store, and IndexedDB serializes
431
+ // a later readonly get() behind it — so running it eagerly on mount could
432
+ // queue the import flow's first cache lookup behind a full scan/delete
433
+ // pass. Deferring to requestIdleCallback lets foreground cache reads
434
+ // create their transactions first; a stale entry served before the sweep
435
+ // runs is harmless (same bytes → same conversion).
436
+ scheduleIdleSweep(cache);
437
+ resolve(cache);
438
+ };
439
+ req.onerror = () => resolve(null);
440
+ });
441
+ }
442
+ /** Run the cache sweep when the browser is idle (or after a short fallback
443
+ * delay where requestIdleCallback is unavailable), so it never precedes the
444
+ * import flow's foreground cache reads. Errors are swallowed — cleanup is
445
+ * best-effort. */
446
+ function scheduleIdleSweep(cache) {
447
+ const run = () => {
448
+ void cache.sweepExpired().catch(() => { });
449
+ };
450
+ const ric = globalThis.requestIdleCallback;
451
+ if (typeof ric === "function") {
452
+ ric(run, { timeout: 10000 });
453
+ }
454
+ else {
455
+ setTimeout(run, 0);
456
+ }
457
+ }
458
+ /** A cache entry is expired when it was written more than CACHE_TTL_MS ago.
459
+ * Exactly at the TTL is kept (strictly-older test). A missing or non-finite
460
+ * ``cachedAt`` (legacy / corrupt record) is treated as expired so the sweep
461
+ * reclaims it. Future-dated entries (clock skew) are kept. */
462
+ export function isCacheEntryExpired(cachedAt, now, ttlMs = CACHE_TTL_MS) {
463
+ if (typeof cachedAt !== "number" || !Number.isFinite(cachedAt))
464
+ return true;
465
+ return now - cachedAt > ttlMs;
466
+ }
467
+ export class IDBConvertCache {
468
+ db;
469
+ constructor(db) {
470
+ this.db = db;
471
+ }
472
+ /** Walk every entry with a readwrite cursor and delete those older than
473
+ * CACHE_TTL_MS. A cursor (rather than getAll) keeps only one record —
474
+ * which carries the full markdown + asset bytes — in memory at a time.
475
+ * Resolves on transaction commit (so the deletes are durable, and a
476
+ * delete-triggered abort surfaces as a rejection rather than a false
477
+ * success); rejects on a transaction/cursor error so the caller can
478
+ * swallow it. ``now`` is injectable for tests. */
479
+ sweepExpired(now = Date.now()) {
480
+ return new Promise((resolve, reject) => {
481
+ let tx;
482
+ try {
483
+ tx = this.db.transaction(DB_STORE, "readwrite");
484
+ }
485
+ catch (err) {
486
+ reject(err);
487
+ return;
488
+ }
489
+ tx.oncomplete = () => resolve();
490
+ tx.onabort = () => reject(tx.error ?? new Error("sweepExpired transaction aborted"));
491
+ tx.onerror = () => reject(tx.error);
492
+ const req = tx.objectStore(DB_STORE).openCursor();
493
+ req.onsuccess = () => {
494
+ const cursor = req.result;
495
+ // Null cursor → iteration done; tx.oncomplete resolves once the
496
+ // queued deletes commit.
497
+ if (!cursor)
498
+ return;
499
+ const record = cursor.value;
500
+ if (isCacheEntryExpired(record?.cachedAt, now)) {
501
+ cursor.delete();
502
+ }
503
+ cursor.continue();
504
+ };
505
+ req.onerror = () => reject(req.error);
506
+ });
507
+ }
508
+ async get(key) {
509
+ const record = await this.txGet(key);
510
+ if (!record || record.mineruVersion !== MINERU_VERSION)
511
+ return null;
512
+ const assets = new Map();
513
+ for (const [path, buf] of record.assets) {
514
+ assets.set(path, new Uint8Array(buf));
515
+ }
516
+ // ``input`` is reconstructed as a synthetic File — callers expect a File,
517
+ // but reflushing the original bytes isn't worth the storage. Use the stem
518
+ // as a stand-in name; downstream code reads .input only for sizing /
519
+ // diagnostics, never for the bytes themselves (those come from the
520
+ // serialized assets + markdown).
521
+ const placeholderName = `${record.stem}.cached`;
522
+ const input = new File([new ArrayBuffer(0)], placeholderName);
523
+ return {
524
+ input,
525
+ inputSha: key,
526
+ stem: record.stem,
527
+ markdown: record.markdown,
528
+ assets,
529
+ };
530
+ }
531
+ async put(key, value) {
532
+ const assets = [];
533
+ for (const [path, bytes] of value.assets) {
534
+ const buf = new ArrayBuffer(bytes.byteLength);
535
+ new Uint8Array(buf).set(bytes);
536
+ assets.push([path, buf]);
537
+ }
538
+ const record = {
539
+ mineruVersion: MINERU_VERSION,
540
+ stem: value.stem,
541
+ markdown: value.markdown,
542
+ assets,
543
+ cachedAt: Date.now(),
544
+ };
545
+ await this.txPut(key, record);
546
+ }
547
+ txGet(key) {
548
+ return new Promise((resolve, reject) => {
549
+ const tx = this.db.transaction(DB_STORE, "readonly");
550
+ const store = tx.objectStore(DB_STORE);
551
+ const req = store.get(key);
552
+ req.onsuccess = () => resolve(req.result);
553
+ req.onerror = () => reject(req.error);
554
+ });
555
+ }
556
+ txPut(key, value) {
557
+ return new Promise((resolve, reject) => {
558
+ const tx = this.db.transaction(DB_STORE, "readwrite");
559
+ const store = tx.objectStore(DB_STORE);
560
+ const req = store.put(value, key);
561
+ req.onsuccess = () => resolve();
562
+ req.onerror = () => reject(req.error);
563
+ });
564
+ }
565
+ }
@@ -0,0 +1,94 @@
1
+ import type { ImportResponse, LintKind, RetrieveStreamEvent, TaskEvent, TaskHandle, TaskListPage, TaskRow, TaskStatus } from "../types/index.js";
2
+ export interface DikwClientConfig {
3
+ baseUrl?: string;
4
+ token?: string;
5
+ /** Stable identifier for the core this client talks to — used by callers
6
+ * that persist task state and must invalidate it if the user reconnects to
7
+ * a different server. Defaults to ``baseUrl`` when omitted, which collapses
8
+ * to the empty string in same-origin proxy mode; pass an explicit value
9
+ * (e.g. the user-visible server URL) to distinguish proxy targets. */
10
+ coreId?: string;
11
+ }
12
+ export interface JsonRequestOptions {
13
+ method?: "GET" | "POST";
14
+ params?: Record<string, string | number | boolean | null | undefined>;
15
+ body?: unknown;
16
+ signal?: AbortSignal;
17
+ }
18
+ export declare class DikwClientError extends Error {
19
+ readonly status: number;
20
+ readonly code: string;
21
+ readonly detail?: Record<string, unknown>;
22
+ constructor(options: {
23
+ status: number;
24
+ code: string;
25
+ message: string;
26
+ detail?: Record<string, unknown>;
27
+ });
28
+ }
29
+ export declare class DikwClient {
30
+ private readonly baseUrl;
31
+ private readonly token;
32
+ private readonly _coreId;
33
+ constructor(config?: DikwClientConfig);
34
+ /** Stable identifier for the core this client talks to. Used by callers that
35
+ * persist task state and must invalidate it if the user reconnects to a
36
+ * different server. */
37
+ get coreId(): string;
38
+ get<T>(path: string, options?: Omit<JsonRequestOptions, "method" | "body">): Promise<T>;
39
+ post<T>(path: string, body?: unknown, options?: Omit<JsonRequestOptions, "method" | "body">): Promise<T>;
40
+ listTasks(params?: {
41
+ status?: TaskStatus;
42
+ op?: string;
43
+ limit?: number;
44
+ cursor?: string;
45
+ }, signal?: AbortSignal): Promise<TaskListPage>;
46
+ getTask(taskId: string, signal?: AbortSignal): Promise<TaskRow>;
47
+ getTaskResult<T = Record<string, unknown>>(taskId: string, signal?: AbortSignal): Promise<T>;
48
+ /**
49
+ * Authoritative terminal verdict for a task, shaped as a synthetic
50
+ * ``type:"final"`` event. ``streamTaskEvents`` decides *when to stop polling*
51
+ * from ``task_status`` + ``has_more``, but pipeline callers read *success*
52
+ * from a captured ``final`` event. Those two signals can disagree within a
53
+ * single ``/events`` response: ``task_status`` is read live (already
54
+ * terminal) while the ``events[]`` tail lags, so a page can report
55
+ * ``{task_status:"succeeded", has_more:false, events:[]}`` and the stream
56
+ * ends without ever yielding the ``final`` event. ``GET /v1/tasks/{id}``
57
+ * reads the authoritative row (the same source the Tasks list shows), so it
58
+ * never loses that race — use it to reconcile when the stream drained without
59
+ * a ``final``. Returns ``null`` if the task is somehow still non-terminal.
60
+ */
61
+ getTaskFinalEvent(taskId: string, signal?: AbortSignal): Promise<Extract<TaskEvent, {
62
+ type: "final";
63
+ }> | null>;
64
+ cancelTask(taskId: string, signal?: AbortSignal): Promise<unknown>;
65
+ importBundle(payload: Blob, manifestJson: string, signal?: AbortSignal): Promise<ImportResponse>;
66
+ startIngest(opts?: {
67
+ noEmbed?: boolean;
68
+ }, signal?: AbortSignal): Promise<TaskHandle>;
69
+ startSynth(opts?: {
70
+ forceAll?: boolean;
71
+ noEmbed?: boolean;
72
+ }, signal?: AbortSignal): Promise<TaskHandle>;
73
+ startLintPropose(opts?: {
74
+ rule?: LintKind | null;
75
+ limit?: number;
76
+ enableLlm?: boolean;
77
+ }, signal?: AbortSignal): Promise<TaskHandle>;
78
+ startLintApply(opts: {
79
+ proposalTaskId: string;
80
+ pick?: number[] | null;
81
+ skip?: number[] | null;
82
+ }, signal?: AbortSignal): Promise<TaskHandle>;
83
+ postMultipart<T>(path: string, form: FormData, signal?: AbortSignal): Promise<T>;
84
+ requestJson<T>(path: string, options?: JsonRequestOptions): Promise<T>;
85
+ streamRetrieve(body: {
86
+ q: string;
87
+ limit: number;
88
+ }, signal?: AbortSignal): AsyncGenerator<RetrieveStreamEvent>;
89
+ streamTaskEvents(taskId: string, fromSeq?: number, signal?: AbortSignal): AsyncGenerator<TaskEvent>;
90
+ streamNdjson<T>(path: string, options?: JsonRequestOptions): AsyncGenerator<T>;
91
+ private headers;
92
+ }
93
+ export declare function buildRequestUrl(baseUrl: string, path: string, params?: Record<string, string | number | boolean | null | undefined>): string;
94
+ export declare function normalizeBaseUrl(value: string): string;