@crossworks/client-types 0.708.1 → 0.709.0

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/client-types",
3
- "version": "0.708.1",
3
+ "version": "0.709.0",
4
4
  "type": "module",
5
5
  "main": "./src/index.ts",
6
6
  "types": "./src/index.ts",
@@ -25,10 +25,27 @@ import type { DataFileState, FileDatabaseReadBy } from './file-databases';
25
25
  * - `none`: not read on purpose: kept to its name, or nothing to read. */
26
26
  export type FileIngest = 'done' | 'partial' | 'waiting' | 'failed' | 'none';
27
27
 
28
- /** An extract job for the file in the queue now: waiting (`queued`) or
29
- * being read (`running`). A file read before can have one: it is being
30
- * read again. */
31
- export type FileJob = 'queued' | 'running';
28
+ /** An extract job for the file in the queue now: waiting its turn
29
+ * (`queued`), being read (`running`), or held until the model provider
30
+ * answers again or, for an Agent's run, the day cap of paid asks has room
31
+ * (`waiting`; FileProcessing.wait says why and when). A file read before
32
+ * can have one: it is being read again. */
33
+ export type FileJob = 'queued' | 'running' | 'waiting';
34
+
35
+ /** Why a file's job waits, and until when (FileProcessing.wait). The
36
+ * provider's "not now": `rate_limit` (too many calls now), `quota` (the
37
+ * account has no credit left), `overloaded` (busy). Nothing is dropped: the
38
+ * job is tried again by itself. */
39
+ export type FileJobWait = {
40
+ for: 'provider' | 'day_cap';
41
+ reason?: 'rate_limit' | 'quota' | 'overloaded';
42
+ /** The Agent pipeline whose run waits, when it is a run. */
43
+ run?: string;
44
+ /** When it is tried again (ISO). */
45
+ until: string;
46
+ /** One sentence for a person. */
47
+ hint: string;
48
+ };
32
49
 
33
50
  export type FileStatus = {
34
51
  ingest: FileIngest;
@@ -72,7 +89,9 @@ export type FileProcessingExtraction = {
72
89
  /** Each kind of cut (docs/files.md, "Read in part"). A `partial` file
73
90
  * has the cuts that made it so; an `indexed` file may carry details
74
91
  * only (`pictures_small`, `pictures_tiny`: icons and small pictures the
75
- * size gate skipped), which are no reason for a partial badge. Each cut:
92
+ * size gate skipped; `archive`, `archive_sealed`: an archive's contents,
93
+ * never read but on a person's "Extract contents", which also make its
94
+ * `reason` and `hint`), which are no reason for a partial badge. Each cut:
76
95
  * its key (`sheet_rows`, `text_store`, `pictures_small`, `ocr_pages`,
77
96
  * `pictures`, `page_pictures`, ...), the unit, how many were read of how many (`atLeast`: the total
78
97
  * is a lower bound), the limit, and its own sentence. */
@@ -173,6 +192,8 @@ export type FileProcessing = {
173
192
  } | null;
174
193
  /** An extract job in the queue now, or null. */
175
194
  job: FileJob | null;
195
+ /** Why the job waits (`job` is `waiting`); absent otherwise. */
196
+ wait?: FileJobWait;
176
197
  /** true: read by an older reader or pipeline version than the box has
177
198
  * now (FileStatus.stale); false: by the current ones; null: unknown (no
178
199
  * stamp: read before the stamps, or not read). */
@@ -240,3 +261,68 @@ export type FileStaleAnswer<Row = { id: string; status: FileStatus }> = {
240
261
  next: string | null;
241
262
  total: number;
242
263
  };
264
+
265
+ /**
266
+ * An archive's "Extract contents" (docs/files.md, "Archives"): never on
267
+ * upload, only on a person's ask. GET /api/files/files/:id/extract answers
268
+ * this for any file the caller reads; POST to the same path asks for the
269
+ * extraction and answers it with the `queued` state. The tool
270
+ * `file_extract_archive` does the same (with `check: true`, the GET).
271
+ */
272
+ export type ArchiveExtractStateName = 'queued' | 'running' | 'done' | 'failed';
273
+
274
+ /** Why one entry of the archive was not written: a path that climbs out
275
+ * (`traversal`) or starts at a root (`absolute`), a name that cannot be
276
+ * one (`bad-name`), a link, a device or FIFO, an encrypted entry, a
277
+ * compression method or entry type this box does not read (`method`,
278
+ * `unsupported`), past the entry cap (`too-large`), bytes that do not
279
+ * match the archive's word (`damaged`), or a write that failed
280
+ * (`not-written`). */
281
+ export type ArchiveEntryRefusal =
282
+ | 'traversal'
283
+ | 'absolute'
284
+ | 'bad-name'
285
+ | 'link'
286
+ | 'device'
287
+ | 'encrypted'
288
+ | 'method'
289
+ | 'unsupported'
290
+ | 'too-large'
291
+ | 'damaged'
292
+ | 'not-written';
293
+
294
+ export type ArchiveExtractView = {
295
+ state: ArchiveExtractStateName;
296
+ /** The folder made beside the archive for its contents (null only for a
297
+ * request whose folder could not be made). */
298
+ folder: { id: string; path: string | null } | null;
299
+ /** When it was asked, started and finished (ISO). */
300
+ queuedAt: string;
301
+ startedAt?: string;
302
+ finishedAt?: string;
303
+ /** So far while running; in all when done. */
304
+ files: number;
305
+ folders: number;
306
+ bytes: number;
307
+ /** macOS and Windows folder files left out (`__MACOSX/`, `.DS_Store`, ...). */
308
+ skipped: number;
309
+ /** Files whose deeper folders went into their name (the tree holds
310
+ * three folder levels below Files). */
311
+ flattened: number;
312
+ /** The first 100 entries not written, each with its reason;
313
+ * `refusedCount` counts them all. */
314
+ refused: { name: string; reason: ArchiveEntryRefusal }[];
315
+ refusedCount: number;
316
+ /** A failed extraction: why, in a sentence. */
317
+ error?: string;
318
+ };
319
+
320
+ export type ArchiveExtractAnswer = {
321
+ file: { id: string; name: string };
322
+ /** Whether "Extract contents" applies: a ZIP, TAR or gzip by its name and
323
+ * its first bytes. `why` says it when not. */
324
+ extractable: boolean;
325
+ why?: string;
326
+ /** The last extraction asked, or null when none was. */
327
+ extract: ArchiveExtractView | null;
328
+ };
package/src/index.ts CHANGED
@@ -179,6 +179,7 @@ export type {
179
179
  FileDerivedItem,
180
180
  FileIngest,
181
181
  FileJob,
182
+ FileJobWait,
182
183
  FileProcessing,
183
184
  FileProcessingExtraction,
184
185
  FileStatus,
@@ -189,6 +190,10 @@ export type {
189
190
  FileReindexAnswer,
190
191
  FileStaleState,
191
192
  FileStaleAnswer,
193
+ ArchiveEntryRefusal,
194
+ ArchiveExtractAnswer,
195
+ ArchiveExtractStateName,
196
+ ArchiveExtractView,
192
197
  } from './dto/file-status';
193
198
  export { FILE_DERIVED_MAX } from './dto/file-status';
194
199
  export { FILE_REINDEX_MAX, FILE_STALE_MAX } from './dto/file-status';