@deepseek-ai/dsh-office-kit 0.0.0-stage → 0.2.2-rc.3
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 +21 -0
- package/README.i18n.yaml +37 -0
- package/README.md +128 -2
- package/README.zh.md +129 -0
- package/lib/index.js +1234 -0
- package/lib/typert.host.d.ts +3 -0
- package/lib/typert.host.js +346 -0
- package/lib/typert.remote-client.d.ts +30 -0
- package/lib/typert.remote-client.d.ts.map +1 -0
- package/lib/typert.remote-client.js +162 -0
- package/lib/types/errors.d.ts +13 -0
- package/lib/types/errors.d.ts.map +1 -0
- package/lib/types/errors.js +15 -0
- package/lib/types/errors.js.map +1 -0
- package/lib/types/identity.d.ts +27 -0
- package/lib/types/identity.d.ts.map +1 -0
- package/lib/types/identity.js +23 -0
- package/lib/types/identity.js.map +1 -0
- package/lib/types/index.d.ts +157 -0
- package/lib/types/index.d.ts.map +1 -0
- package/lib/types/index.js +459 -0
- package/lib/types/index.js.map +1 -0
- package/lib/types/locate.d.ts +48 -0
- package/lib/types/locate.d.ts.map +1 -0
- package/lib/types/locate.js +65 -0
- package/lib/types/locate.js.map +1 -0
- package/lib/types/output.d.ts +26 -0
- package/lib/types/output.d.ts.map +1 -0
- package/lib/types/output.js +75 -0
- package/lib/types/output.js.map +1 -0
- package/lib/types/outputs.d.ts +75 -0
- package/lib/types/outputs.d.ts.map +1 -0
- package/lib/types/outputs.js +198 -0
- package/lib/types/outputs.js.map +1 -0
- package/lib/types/queue.d.ts +106 -0
- package/lib/types/queue.d.ts.map +1 -0
- package/lib/types/queue.js +276 -0
- package/lib/types/queue.js.map +1 -0
- package/lib/types/types.d.ts +151 -0
- package/lib/types/types.d.ts.map +1 -0
- package/lib/types/types.js +2 -0
- package/lib/types/types.js.map +1 -0
- package/locale/de.json +6 -0
- package/locale/en.json +6 -0
- package/locale/es.json +6 -0
- package/locale/fr.json +6 -0
- package/locale/ja.json +6 -0
- package/locale/pt.json +6 -0
- package/locale/ru.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +68 -3
- package/src/errors.ts +15 -0
- package/src/identity.ts +31 -0
- package/src/index.ts +484 -0
- package/src/locate.ts +93 -0
- package/src/output.ts +69 -0
- package/src/outputs.ts +218 -0
- package/src/queue.ts +316 -0
- 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
|
+
}
|