@deepseek-ai/dsh-office-kit 0.0.0-stage → 0.2.2-rc.2

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 (59) hide show
  1. package/LICENSE +21 -0
  2. package/README.i18n.yaml +37 -0
  3. package/README.md +128 -2
  4. package/README.zh.md +129 -0
  5. package/lib/index.js +1234 -0
  6. package/lib/typert.host.d.ts +3 -0
  7. package/lib/typert.host.js +346 -0
  8. package/lib/typert.remote-client.d.ts +30 -0
  9. package/lib/typert.remote-client.d.ts.map +1 -0
  10. package/lib/typert.remote-client.js +162 -0
  11. package/lib/types/errors.d.ts +13 -0
  12. package/lib/types/errors.d.ts.map +1 -0
  13. package/lib/types/errors.js +15 -0
  14. package/lib/types/errors.js.map +1 -0
  15. package/lib/types/identity.d.ts +27 -0
  16. package/lib/types/identity.d.ts.map +1 -0
  17. package/lib/types/identity.js +23 -0
  18. package/lib/types/identity.js.map +1 -0
  19. package/lib/types/index.d.ts +157 -0
  20. package/lib/types/index.d.ts.map +1 -0
  21. package/lib/types/index.js +459 -0
  22. package/lib/types/index.js.map +1 -0
  23. package/lib/types/locate.d.ts +48 -0
  24. package/lib/types/locate.d.ts.map +1 -0
  25. package/lib/types/locate.js +65 -0
  26. package/lib/types/locate.js.map +1 -0
  27. package/lib/types/output.d.ts +26 -0
  28. package/lib/types/output.d.ts.map +1 -0
  29. package/lib/types/output.js +75 -0
  30. package/lib/types/output.js.map +1 -0
  31. package/lib/types/outputs.d.ts +75 -0
  32. package/lib/types/outputs.d.ts.map +1 -0
  33. package/lib/types/outputs.js +198 -0
  34. package/lib/types/outputs.js.map +1 -0
  35. package/lib/types/queue.d.ts +106 -0
  36. package/lib/types/queue.d.ts.map +1 -0
  37. package/lib/types/queue.js +276 -0
  38. package/lib/types/queue.js.map +1 -0
  39. package/lib/types/types.d.ts +151 -0
  40. package/lib/types/types.d.ts.map +1 -0
  41. package/lib/types/types.js +2 -0
  42. package/lib/types/types.js.map +1 -0
  43. package/locale/de.json +6 -0
  44. package/locale/en.json +6 -0
  45. package/locale/es.json +6 -0
  46. package/locale/fr.json +6 -0
  47. package/locale/ja.json +6 -0
  48. package/locale/pt.json +6 -0
  49. package/locale/ru.json +6 -0
  50. package/locale/zh.json +6 -0
  51. package/package.json +68 -3
  52. package/src/errors.ts +15 -0
  53. package/src/identity.ts +31 -0
  54. package/src/index.ts +484 -0
  55. package/src/locate.ts +93 -0
  56. package/src/output.ts +69 -0
  57. package/src/outputs.ts +218 -0
  58. package/src/queue.ts +316 -0
  59. package/src/types.ts +168 -0
package/src/queue.ts ADDED
@@ -0,0 +1,316 @@
1
+ /** Bounded source admission, shared content conversion, and caller-owned output delivery. */
2
+ import { createHash } from 'node:crypto'
3
+ import { OfficeKitError } from './errors.ts'
4
+ import { OfficeKitKey, type OfficeKitGeneration } from './identity.ts'
5
+ import type {
6
+ OfficeConversionFormat, OfficeImage, OfficeKitPriority, OfficeKitSource, OfficeRecalculationFormat,
7
+ } from './types.ts'
8
+ import type { Config } from './index.ts'
9
+
10
+ /** Engine operation applied to one admitted source; its JSON form distinguishes cached outputs. */
11
+ export type OfficeOperation =
12
+ | { readonly kind: 'pdf' }
13
+ | {
14
+ readonly kind: 'images'
15
+ readonly pages?: readonly number[]
16
+ readonly sheet?: string
17
+ readonly range?: string
18
+ readonly dpi?: number
19
+ readonly maxImages: number
20
+ readonly maxPixels: number
21
+ readonly maxDimension: number
22
+ readonly maxBytes: number
23
+ }
24
+ | { readonly kind: 'convert'; readonly format: OfficeConversionFormat; readonly sheet?: string }
25
+ | { readonly kind: 'recalculate'; readonly format: OfficeRecalculationFormat }
26
+
27
+ /** Complete engine output for one operation kind. */
28
+ export type OfficeOperationOutput =
29
+ | { readonly kind: 'pdf'; readonly pdf: Uint8Array; readonly missingFonts: string[] }
30
+ | {
31
+ readonly kind: 'images'
32
+ readonly images: readonly OfficeImage[]
33
+ readonly pageCount: number
34
+ readonly dpi: number
35
+ readonly missingFonts: string[]
36
+ }
37
+ | { readonly kind: 'file'; readonly data: Uint8Array; readonly pageCount?: number; readonly missingFonts: string[] }
38
+
39
+ /** Output kind produced by each operation. */
40
+ export type OutputOf<O extends OfficeOperation> = Extract<OfficeOperationOutput, { kind: O['kind'] extends 'convert' | 'recalculate' ? 'file' : O['kind'] }>
41
+
42
+ /** One admitted operation on an authorized source. */
43
+ export interface QueueRequest<O extends OfficeOperation = OfficeOperation> {
44
+ readonly extension: string
45
+ readonly priority: OfficeKitPriority
46
+ readonly source: OfficeKitSource
47
+ readonly operation: O
48
+ }
49
+
50
+ /** Caller-owned output with its converter-owned identity. */
51
+ export type QueueResult<O extends OfficeOperation = OfficeOperation> = OutputOf<O> & {
52
+ readonly cacheKey: OfficeKitKey
53
+ readonly generation: OfficeKitGeneration
54
+ }
55
+
56
+ type Stored = OfficeOperationOutput & { readonly cacheKey: OfficeKitKey; readonly generation: OfficeKitGeneration }
57
+ type Convert = (bytes: Uint8Array, request: Pick<QueueRequest, 'extension' | 'operation'>, signal: AbortSignal) => Promise<OfficeOperationOutput>
58
+ interface Reader {
59
+ job: Job
60
+ readonly source: string
61
+ readonly priority: OfficeKitPriority
62
+ readonly resolve: (value: Stored) => void
63
+ readonly reject: (error: unknown) => void
64
+ readonly cleanup: () => void
65
+ }
66
+ interface Job {
67
+ readonly request: QueueRequest
68
+ readonly operation: string
69
+ readonly controller: AbortController
70
+ readonly readers: Set<Reader>
71
+ readonly sources: Set<string>
72
+ priority: OfficeKitPriority
73
+ state: 'queued' | 'running' | 'finished'
74
+ }
75
+
76
+ /** Bytes a retained output occupies. */
77
+ function outputBytes(output: OfficeOperationOutput): number {
78
+ switch (output.kind) {
79
+ case 'pdf': return output.pdf.byteLength
80
+ case 'file': return output.data.byteLength
81
+ case 'images': return output.images.reduce((sum, image) => sum + image.png.byteLength, 0)
82
+ /* v8 ignore next -- OfficeOperationOutput is a closed union */
83
+ default: return exhausted(output)
84
+ }
85
+ }
86
+
87
+ /** Independent copy of every byte array and list in an output. */
88
+ function copyOutput(result: Stored): Stored {
89
+ switch (result.kind) {
90
+ case 'pdf': return { ...result, pdf: Uint8Array.from(result.pdf), missingFonts: [...result.missingFonts] }
91
+ case 'file': return { ...result, data: Uint8Array.from(result.data), missingFonts: [...result.missingFonts] }
92
+ case 'images': return { ...result, missingFonts: [...result.missingFonts],
93
+ images: result.images.map(image => ({ ...image, png: Uint8Array.from(image.png) })) }
94
+ /* v8 ignore next -- OfficeOperationOutput is a closed union */
95
+ default: return exhausted(result)
96
+ }
97
+ }
98
+
99
+ /* v8 ignore next 3 -- reached only through an unchecked closed-union member */
100
+ function exhausted(value: never): never {
101
+ throw new Error(`Unexpected Office output: ${JSON.stringify(value)}`)
102
+ }
103
+
104
+ /** One converter generation owns every queued source, conversion, reader, and retained PDF. */
105
+ export class ConversionQueue {
106
+ private readonly ready = new Map<OfficeKitKey, Stored>()
107
+ private readonly aliases = new Map<string, OfficeKitKey>()
108
+ private readonly sources = new Map<string, Job>()
109
+ private readonly digests = new Map<OfficeKitKey, Job>()
110
+ private readonly queue: Job[] = []
111
+ private readonly tasks = new Set<Promise<void>>()
112
+ private readonly jobs = new Set<Job>()
113
+ private cachedBytes = 0
114
+ private sourceBytes = 0
115
+ private running = 0
116
+ private background = 0
117
+ private readers = 0
118
+ private disposed = false
119
+
120
+ /**
121
+ * @param config - validated queue, source, reader, and completed-result limits.
122
+ * @param generation - provider lifetime; prevents reuse after engine or font replacement.
123
+ * @param convert - executes one admitted conversion and settles after scratch cleanup.
124
+ */
125
+ constructor(private readonly config: Config, private readonly generation: OfficeKitGeneration,
126
+ private readonly convert: Convert) {}
127
+
128
+ /**
129
+ * Admit metadata before loading source bytes and share conversion across authorized readers.
130
+ * @param request - already-authorized metadata and deferred bounded source read.
131
+ * @param signal - this reader's cancellation; the final reader cancels shared work.
132
+ * @returns independent output bytes; busy or canceled readers reject without releasing active engine capacity early.
133
+ */
134
+ async read<O extends OfficeOperation>(request: QueueRequest<O>, signal?: AbortSignal): Promise<QueueResult<O>> {
135
+ // The stored output was produced for this request's operation kind.
136
+ return await this.readStored(request, signal) as QueueResult<O>
137
+ }
138
+
139
+ private async readStored(request: QueueRequest, signal?: AbortSignal): Promise<Stored> {
140
+ signal?.throwIfAborted()
141
+ if (this.disposed) throw this.unavailable()
142
+ if (request.source.bytes !== undefined && request.source.bytes > this.config.maxInputBytes) {
143
+ throw new OfficeKitError('input-too-large', 'The Office source exceeds maxInputBytes.')
144
+ }
145
+ const operation = JSON.stringify(request.operation)
146
+ const source = JSON.stringify([request.source.key, request.source.version, request.extension, operation])
147
+ const alias = this.aliases.get(source)
148
+ const cached = alias === undefined ? undefined : this.ready.get(alias)
149
+ if (cached !== undefined) {
150
+ this.ready.delete(cached.cacheKey)
151
+ this.ready.set(cached.cacheKey, cached)
152
+ this.aliases.delete(source)
153
+ this.aliases.set(source, cached.cacheKey)
154
+ return this.copy(cached)
155
+ }
156
+ const readerLimit = request.priority === 'background' ? this.config.maxReaders - 1 : this.config.maxReaders
157
+ if (this.readers >= readerLimit) throw this.busy()
158
+ if (request.priority === 'background' && this.config.maxBackgroundConversions === 0) throw this.busy()
159
+ let job = this.sources.get(source)
160
+ if (job === undefined) {
161
+ if (this.queue.length >= this.config.maxQueuedJobs) {
162
+ const obsolete = request.priority === 'foreground' ? this.queue.find(item => item.priority === 'background') : undefined
163
+ if (obsolete === undefined) throw this.busy()
164
+ this.fail(obsolete, this.busy())
165
+ }
166
+ job = { request, operation, priority: request.priority, controller: new AbortController(), readers: new Set(), sources: new Set([source]), state: 'queued' }
167
+ this.sources.set(source, job)
168
+ this.jobs.add(job)
169
+ this.queue.push(job)
170
+ }
171
+ const shared = job
172
+ if (request.priority === 'foreground') shared.priority = 'foreground'
173
+ this.readers++
174
+ const promise = new Promise<Stored>((resolve, reject) => {
175
+ const abort = (): void => {
176
+ this.release(reader)
177
+ const reason: unknown = signal?.reason
178
+ reject(reason instanceof Error ? reason : new Error('Office conversion cancelled', { cause: reason }))
179
+ if (reader.job.readers.size === 0) this.cancel(reader.job)
180
+ // Cancellation or demotion can unblock queued background work.
181
+ this.drain()
182
+ }
183
+ const reader: Reader = { job: shared, source, priority: request.priority, resolve, reject, cleanup: () => signal?.removeEventListener('abort', abort) }
184
+ shared.readers.add(reader)
185
+ signal?.addEventListener('abort', abort, { once: true })
186
+ })
187
+ this.drain()
188
+ return promise
189
+ }
190
+
191
+ /** Cancel all readers and wait until actual reads, conversions, and scratch cleanup finish. */
192
+ async dispose(): Promise<void> {
193
+ this.disposed = true
194
+ for (const job of this.jobs) this.fail(job, this.unavailable())
195
+ this.ready.clear()
196
+ this.aliases.clear()
197
+ this.cachedBytes = 0
198
+ await Promise.allSettled(this.tasks)
199
+ }
200
+
201
+ private busy(): OfficeKitError { return new OfficeKitError('busy', 'The document converter has reached its admission limit.') }
202
+ private unavailable(): OfficeKitError { return new OfficeKitError('unavailable', 'The document converter is unavailable.') }
203
+ private copy(result: Stored): Stored { return copyOutput(result) }
204
+ private release(reader: Reader): void {
205
+ reader.job.readers.delete(reader)
206
+ if (reader.job.state === 'queued') {
207
+ reader.job.priority = [...reader.job.readers].some(other => other.priority === 'foreground') ? 'foreground' : 'background'
208
+ }
209
+ if (![...reader.job.readers].some(other => other.source === reader.source)) {
210
+ reader.job.sources.delete(reader.source)
211
+ if (this.sources.get(reader.source) === reader.job) this.sources.delete(reader.source)
212
+ }
213
+ reader.cleanup()
214
+ this.readers--
215
+ }
216
+ private cancel(job: Job): void {
217
+ job.controller.abort()
218
+ if (job.state === 'queued') {
219
+ this.queue.splice(this.queue.indexOf(job), 1)
220
+ job.state = 'finished'
221
+ this.jobs.delete(job)
222
+ }
223
+ }
224
+ private fail(job: Job, error: unknown): void {
225
+ for (const reader of job.readers) { this.release(reader); reader.reject(error) }
226
+ this.cancel(job)
227
+ }
228
+ private reservation(job: Job): number { return Math.max(1, job.request.source.bytes ?? this.config.maxInputBytes) }
229
+
230
+ private drain(): void {
231
+ while (!this.disposed && this.running < this.config.maxConcurrentConversions) {
232
+ const eligible = (job: Job): boolean => this.sourceBytes + this.reservation(job) <= this.config.maxSourceBytes
233
+ && (job.priority === 'foreground' || this.background < Math.min(this.config.maxBackgroundConversions, Math.max(1, this.config.maxConcurrentConversions - 1)))
234
+ const foregroundWaiting = this.queue.some(item => item.priority === 'foreground')
235
+ const job = this.queue.find(item => (!foregroundWaiting || item.priority === 'foreground') && eligible(item))
236
+ if (job === undefined) return
237
+ this.queue.splice(this.queue.indexOf(job), 1)
238
+ job.state = 'running'
239
+ const background = job.priority === 'background'
240
+ const reserved = this.reservation(job)
241
+ this.running++
242
+ if (background) this.background++
243
+ this.sourceBytes += reserved
244
+ const task = this.execute(job, reserved).catch((error: unknown) => { this.fail(job, error) }).finally(() => {
245
+ this.running--
246
+ if (background) this.background--
247
+ this.sourceBytes -= reserved
248
+ job.state = 'finished'
249
+ this.jobs.delete(job)
250
+ this.tasks.delete(task)
251
+ this.drain()
252
+ })
253
+ this.tasks.add(task)
254
+ }
255
+ }
256
+
257
+ private async execute(job: Job, reserved: number): Promise<void> {
258
+ const signal = job.controller.signal
259
+ signal.throwIfAborted()
260
+ const input = await job.request.source.read(signal, reserved)
261
+ signal.throwIfAborted()
262
+ if (input.version !== job.request.source.version) throw new OfficeKitError('source-changed', 'The source changed while waiting for conversion.')
263
+ if (input.bytes.byteLength > reserved) throw new OfficeKitError('input-too-large', 'The source exceeds its reserved read capacity.')
264
+ const digest = createHash('sha256').update(job.request.extension).update('\0').update(job.operation).update('\0')
265
+ .update(input.bytes).digest('hex')
266
+ const key = OfficeKitKey(`${this.generation}:${digest}`)
267
+ const cached = this.ready.get(key)
268
+ if (cached !== undefined) {
269
+ this.ready.delete(key)
270
+ this.ready.set(key, cached)
271
+ this.finish(job, cached)
272
+ return
273
+ }
274
+ const existing = this.digests.get(key)
275
+ if (existing !== undefined && !existing.controller.signal.aborted) {
276
+ if (job.priority === 'foreground') existing.priority = 'foreground'
277
+ for (const reader of job.readers) { reader.job = existing; existing.readers.add(reader) }
278
+ job.readers.clear()
279
+ for (const source of job.sources) { existing.sources.add(source); this.sources.set(source, existing) }
280
+ job.sources.clear()
281
+ return
282
+ }
283
+ this.digests.set(key, job)
284
+ try {
285
+ const converted = await this.convert(input.bytes, job.request, signal)
286
+ signal.throwIfAborted()
287
+ const result: Stored = { ...converted, cacheKey: key, generation: this.generation }
288
+ this.retain(result)
289
+ this.finish(job, result)
290
+ } finally { if (this.digests.get(key) === job) this.digests.delete(key) }
291
+ }
292
+
293
+ private finish(job: Job, result: Stored): void {
294
+ for (const source of job.sources) this.sources.delete(source)
295
+ if (this.ready.has(result.cacheKey)) {
296
+ for (const source of job.sources) {
297
+ this.aliases.delete(source)
298
+ this.aliases.set(source, result.cacheKey)
299
+ while (this.aliases.size > this.config.maxSourceEntries) this.aliases.delete(this.aliases.keys().next().value as string)
300
+ }
301
+ }
302
+ for (const reader of job.readers) { this.release(reader); reader.resolve(this.copy(result)) }
303
+ }
304
+ private retain(result: Stored): void {
305
+ const bytes = outputBytes(result)
306
+ if (bytes > this.config.maxCachedBytes) return
307
+ while (this.ready.size >= this.config.maxCachedEntries || this.cachedBytes + bytes > this.config.maxCachedBytes) {
308
+ const [key, oldest] = this.ready.entries().next().value as [OfficeKitKey, Stored]
309
+ this.ready.delete(key)
310
+ this.cachedBytes -= outputBytes(oldest)
311
+ for (const [source, digest] of this.aliases) if (digest === key) this.aliases.delete(source)
312
+ }
313
+ this.ready.set(result.cacheKey, result)
314
+ this.cachedBytes += bytes
315
+ }
316
+ }
package/src/types.ts ADDED
@@ -0,0 +1,168 @@
1
+ /** Authorized Office input and complete outputs of the shared Host converter. */
2
+ import type { WorkspaceFileBytes } from '@deepseek-ai/dsh-api-workspace-files/types'
3
+ import type {} from '@deepseek-ai/dsh-typert-protocol'
4
+ import type { OfficeSourceKey, OfficeKitGeneration, OfficeKitKey } from './identity.ts'
5
+ export type { OfficeSourceKey, OfficeKitGeneration, OfficeKitKey } from './identity.ts'
6
+
7
+ /** Binary Office and Office Open XML formats accepted by PDF previews, image rendering, and format conversion. */
8
+ export type OfficeExtension = 'doc' | 'docx' | 'xls' | 'xlsx' | 'ppt' | 'pptx'
9
+
10
+ /** Foreground previews and explicit QA precede speculative background conversion. */
11
+ export type OfficeKitPriority = 'foreground' | 'background'
12
+
13
+ /** Authorized source metadata and its deferred bounded read. */
14
+ export interface OfficeKitSource {
15
+ readonly key: OfficeSourceKey
16
+ readonly version: string
17
+ /** Authorized stat size; omission reserves the provider's entire input limit. */
18
+ readonly bytes?: number
19
+ /**
20
+ * Read only after provider admission; do not capture already-buffered input in queued production requests.
21
+ * @param signal - shared conversion lifetime, independent of an individual reader.
22
+ * @param maxBytes - reserved source capacity; read at most this plus one overflow sentinel byte.
23
+ * @returns owned bytes and the actual read version; a changed version rejects conversion.
24
+ */
25
+ read(signal: AbortSignal, maxBytes: number): Promise<{ readonly bytes: Uint8Array; readonly version: string }>
26
+ }
27
+
28
+ /** Source authorization and metadata lookup must finish before submitting a request. */
29
+ export interface OfficeKitRequest {
30
+ readonly extension: OfficeExtension
31
+ readonly priority: OfficeKitPriority
32
+ readonly source: OfficeKitSource
33
+ }
34
+
35
+ /** Office, OpenDocument, and PDF inputs accepted by image rendering. */
36
+ export type OfficeImageInputExtension = OfficeDocumentExtension | 'pdf'
37
+
38
+ /** Office and OpenDocument inputs accepted by format conversion. */
39
+ export type OfficeDocumentExtension = OfficeExtension | 'odt' | 'ods' | 'odp'
40
+
41
+ /** Workbook inputs accepted by recalculation. */
42
+ export type OfficeWorkbookExtension = 'xls' | 'xlsx' | 'ods'
43
+
44
+ /** Format-conversion outputs; the engine accepts only the outputs of the input's document family. */
45
+ export type OfficeConversionFormat = 'pdf' | 'docx' | 'odt' | 'txt' | 'xlsx' | 'ods' | 'csv' | 'pptx' | 'odp'
46
+
47
+ /** Recalculated workbook outputs. */
48
+ export type OfficeRecalculationFormat = 'xlsx' | 'ods'
49
+
50
+ /**
51
+ * Render selected pages, slides, or worksheet areas of one document as PNG images.
52
+ * Worksheets select `sheet` and an optional A1 `range` and reject `pages`; other documents reject `sheet` and `range`.
53
+ */
54
+ export interface OfficeImagesRequest {
55
+ readonly extension: OfficeImageInputExtension
56
+ readonly source: OfficeKitSource
57
+ /** Distinct one-based pages or slides; omission renders every page. */
58
+ readonly pages?: readonly number[]
59
+ /** Exact worksheet name; omission renders each visible worksheet's data area. */
60
+ readonly sheet?: string
61
+ /** A1 rectangle inside `sheet`. */
62
+ readonly range?: string
63
+ /** Raster resolution from 24 to 600; omission uses the engine default. */
64
+ readonly dpi?: number
65
+ /** Inclusive count of returned images, including worksheet fragments; a larger selection rejects. */
66
+ readonly maxImages: number
67
+ /** Inclusive pixel count of each image. */
68
+ readonly maxPixels: number
69
+ /** Inclusive width and height of each image. */
70
+ readonly maxDimension: number
71
+ /** Inclusive PNG bytes across all returned images. */
72
+ readonly maxBytes: number
73
+ }
74
+
75
+ /** One rendered PNG and the document location it shows. */
76
+ export interface OfficeImage {
77
+ /** Caller-owned PNG bytes. */
78
+ readonly png: Uint8Array
79
+ readonly width: number
80
+ readonly height: number
81
+ /** One-based page or slide; absent for worksheet areas. */
82
+ readonly page?: number
83
+ /** Worksheet name for worksheet areas. */
84
+ readonly sheet?: string
85
+ /** A1 rectangle for worksheet areas. */
86
+ readonly range?: string
87
+ }
88
+
89
+ /** Successful image rendering; failed and interrupted renders reject instead. */
90
+ export interface OfficeImagesResult {
91
+ /** Images in document order. */
92
+ readonly images: readonly OfficeImage[]
93
+ /** Pages, slides, or visible worksheets in the document. */
94
+ readonly pageCount: number
95
+ /** Raster resolution used. */
96
+ readonly dpi: number
97
+ /** Requested OOXML font families unavailable to this rendering. */
98
+ readonly missingFonts: string[]
99
+ }
100
+
101
+ /** Owner and file name of a converted or recalculated output saved in the provider's output store. */
102
+ export interface OfficeOutputTarget {
103
+ /** Opaque owner, normally a Session id; disposing the Session with this id deletes its outputs, and other Sessions' disposal does not. */
104
+ readonly owner: string
105
+ /** File name without directories, including the output extension. */
106
+ readonly name: string
107
+ }
108
+
109
+ /** Convert one document to the format named by `format`; CSV requires `sheet` for a workbook with several sheets. */
110
+ export interface OfficeConversionRequest {
111
+ readonly extension: OfficeDocumentExtension
112
+ readonly format: OfficeConversionFormat
113
+ /** Exact worksheet name; accepted only for CSV output. */
114
+ readonly sheet?: string
115
+ readonly source: OfficeKitSource
116
+ readonly output: OfficeOutputTarget
117
+ }
118
+
119
+ /** Recalculate every formula of one workbook and save it with refreshed cached results. */
120
+ export interface OfficeRecalculationRequest {
121
+ readonly extension: OfficeWorkbookExtension
122
+ readonly format: OfficeRecalculationFormat
123
+ readonly source: OfficeKitSource
124
+ readonly output: OfficeOutputTarget
125
+ }
126
+
127
+ /** Successful conversion or recalculation saved in the output store; failed and interrupted operations reject instead. */
128
+ export interface OfficeFileResult {
129
+ /** Absolute Host path of the saved file, readable by the same OS user until retention, release, or disposal deletes it. */
130
+ readonly path: string
131
+ /** Complete file bytes, bounded by `maxOutputBytes`. */
132
+ readonly bytes: number
133
+ /** Page count the converter reports for the output. */
134
+ readonly pageCount?: number
135
+ /** Requested OOXML font families unavailable to this operation. */
136
+ readonly missingFonts: string[]
137
+ }
138
+
139
+ /** Successful conversion; failed and interrupted conversions reject instead. */
140
+ export interface OfficeKitResult {
141
+ /** Caller-owned complete PDF, valid after provider disposal. */
142
+ readonly pdf: Uint8Array
143
+ /** Requested OOXML font families unavailable to this conversion; binary Office formats return an empty list. */
144
+ readonly missingFonts: string[]
145
+ readonly cacheKey: OfficeKitKey
146
+ readonly generation: OfficeKitGeneration
147
+ }
148
+
149
+ /**
150
+ * Failures a conversion consumer can present without exposing engine diagnostics. `invalid-request` carries the
151
+ * engine's description of a rejected page, sheet, range, resolution, or format selection.
152
+ */
153
+ export type OfficeKitErrorCode =
154
+ | 'input-too-large' | 'output-too-large' | 'invalid-document' | 'unsupported-format'
155
+ | 'invalid-output' | 'timeout' | 'unavailable' | 'failed' | 'busy' | 'source-changed' | 'invalid-request'
156
+
157
+ /** PDF content carries the original Office file's identity and multipart-transferred bytes. */
158
+ export interface RenderedDocumentBytes extends WorkspaceFileBytes {
159
+ readonly missingFonts: string[]
160
+ readonly generation: OfficeKitGeneration
161
+ }
162
+
163
+ declare module '@deepseek-ai/dsh-typert-protocol' {
164
+ interface RemoteErrorDetailsMap {
165
+ /** The source was authorized, but its conversion failed. */
166
+ 'document-render/failed': { readonly reason: OfficeKitErrorCode }
167
+ }
168
+ }