@crossworks/client-types 0.705.0 → 0.706.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.705.0",
3
+ "version": "0.706.0",
4
4
  "type": "module",
5
5
  "main": "./src/index.ts",
6
6
  "types": "./src/index.ts",
@@ -0,0 +1,87 @@
1
+ /**
2
+ * File history (docs/files.md, "File history"): what the client reads back
3
+ * from the upload when a name is taken, and from the history routes.
4
+ *
5
+ * - POST /api/files/files (multipart, no `replace`): a name already in the
6
+ * folder with the SAME bytes answers 200 `UploadSkippedResponse`
7
+ * ("Already here"); with other bytes 409 `UploadClashResponse`, so the
8
+ * client can ask Override / Override all / Skip / Skip all. Override is
9
+ * the same upload again with `replace=true`.
10
+ * - GET /api/files/files/:id/history FileHistoryResponse
11
+ * - GET /api/files/files/:id/history/:sid/download the bytes
12
+ * - POST /api/files/files/:id/history/:sid/restore FileRestoreResponse
13
+ * - DELETE /api/files/files/:id/history/:sid { ok: true }
14
+ *
15
+ * Reading the history and downloading a version: whoever reads the file.
16
+ * Restore and delete of a version: a Moderator of the file's workspace, a
17
+ * Moderator of a workspace that holds it, or an Admin user (never a plain
18
+ * user with Write on): `FileHistoryRights.mayRestore`.
19
+ */
20
+
21
+ /** Why a version was kept: new bytes replaced it (an upload with replace,
22
+ * an edit, an export saved again), or a restore did. */
23
+ export type FileVersionTrigger = 'replace' | 'pre_restore';
24
+
25
+ /** One kept version of a file, newest first in a list. */
26
+ export type FileVersion = {
27
+ /** The version's id (the `:sid` of its routes). */
28
+ id: string;
29
+ /** v1, v2 ... per file, never reused. */
30
+ seq: number;
31
+ trigger: FileVersionTrigger;
32
+ /** When these bytes stopped being the file's (ISO). */
33
+ createdAt: string;
34
+ sizeBytes: number;
35
+ sha256: string | null;
36
+ /** The file's name when these bytes were its. */
37
+ filename: string | null;
38
+ /** Who replaced them: HISTORY_ACTORS (@mantle/client-types/role-names). */
39
+ actor: string;
40
+ /** A `pre_restore` version: the seq the restore put back. */
41
+ restoredFrom: number | null;
42
+ };
43
+
44
+ /** What the caller may do with the versions. */
45
+ export type FileHistoryRights = {
46
+ /** Restore a version, and delete one. */
47
+ mayRestore: boolean;
48
+ };
49
+
50
+ /** GET /api/files/files/:id/history. */
51
+ export type FileHistoryResponse = {
52
+ versions: FileVersion[];
53
+ rights: FileHistoryRights;
54
+ };
55
+
56
+ /** POST /api/files/files/:id/history/:sid/restore: the file as it is now
57
+ * (the restored bytes), and the version restored. The bytes it replaced
58
+ * are kept as a new `pre_restore` version, so a restore is undone by
59
+ * restoring that one. */
60
+ export type FileRestoreResponse = {
61
+ /** The file row (as GET /api/files/files/:id answers `file`). */
62
+ file: { id: string; sha256: string | null; sizeBytes: number; filename: string };
63
+ restored: FileVersion;
64
+ };
65
+
66
+ /** The file already in the folder under the uploaded name. */
67
+ export type UploadExistingFile = {
68
+ id: string;
69
+ sha256: string | null;
70
+ sizeBytes: number;
71
+ name: string;
72
+ };
73
+
74
+ /** 200 from the upload: the same bytes are already there under that name.
75
+ * Nothing was written. */
76
+ export type UploadSkippedResponse = {
77
+ skipped: true;
78
+ reason: 'same-bytes';
79
+ existing: Pick<UploadExistingFile, 'id' | 'sha256'>;
80
+ };
81
+
82
+ /** 409 from the upload: the name is taken by other bytes. */
83
+ export type UploadClashResponse = {
84
+ error: string;
85
+ reason: 'name-taken';
86
+ existing: UploadExistingFile;
87
+ };
@@ -0,0 +1,200 @@
1
+ /**
2
+ * A file's status and its processing, as Files shows them (docs/files.md,
3
+ * "Status and processing"):
4
+ *
5
+ * - `FileStatus`: the compact status on every file row of
6
+ * GET /api/files/files (a folder, Recent, by read state), on the one
7
+ * file of GET /api/files/files/:id, and on a file's TreeItem
8
+ * (GET /api/tree/files...). What the corner badge of a file's icon draws.
9
+ * - `FileProcessing`: GET /api/files/files/:id/processing and the
10
+ * `file_processing` tool. What the Details panel draws: size, pages, was
11
+ * it embedded, the counts, the database, the queue, the last error, and
12
+ * where its content went (the items made from it).
13
+ *
14
+ * Both are derived live from the file row, the queue and the file's
15
+ * database on disk; nothing new is stored.
16
+ */
17
+ import type { DataFileState, FileDatabaseReadBy } from './file-databases';
18
+
19
+ /** Was the file's content read into the brain:
20
+ * - `done`: read, in search (facts and mentions where the reader makes them);
21
+ * - `partial`: read in part (a scan's first pages: `FileProcessing.extraction.pages`);
22
+ * - `waiting`: not read yet (queued, retrying, or about to be queued);
23
+ * - `failed`: the read failed (`FileProcessing.error` says why);
24
+ * - `none`: not read on purpose: kept to its name, or nothing to read. */
25
+ export type FileIngest = 'done' | 'partial' | 'waiting' | 'failed' | 'none';
26
+
27
+ /** An extract job for the file in the queue now: waiting (`queued`) or
28
+ * being read (`running`). A file read before can have one: it is being
29
+ * read again. */
30
+ export type FileJob = 'queued' | 'running';
31
+
32
+ export type FileStatus = {
33
+ ingest: FileIngest;
34
+ /** Absent when no job for the file is in the queue. */
35
+ job?: FileJob;
36
+ /** The file's own database (its Data view): `ready`, a word for why it
37
+ * has no rows (`too-large`, `no-rows`, `unreadable`: unreadable is the
38
+ * failed one), or `not-built` yet. Absent for a file that has no Data
39
+ * view. */
40
+ db?: DataFileState;
41
+ /** Sent only when true: the file was read by an older reader (or its
42
+ * database by an older pipeline version) than the box has now, so a
43
+ * reindex would read it better. Absent: current, or unknown (read before
44
+ * the stamps). */
45
+ stale?: boolean;
46
+ /** The name of the Reader pipeline that built the file's database.
47
+ * Absent when none did (no database, or built before the stamps). */
48
+ pipeline?: string;
49
+ };
50
+
51
+ /** What read a file's text: the core reader of its type (the parser
52
+ * route: 'pdf-parse', 'mammoth', 'exceljs', 'utf8', ..., or 'image' for a
53
+ * picture read by vision) and its version then. FileRow.readBy. */
54
+ export type FileReadBy = { reader: string; v: number };
55
+
56
+ /** The Reader pipeline that built a file's database, and its version
57
+ * then. FileRow.pipelineRead. */
58
+ export type FilePipelineRead = { id: string; name: string; version: string };
59
+
60
+ /** The read state of the file, as FileRow.extraction (the brain's
61
+ * extraction-status rule). */
62
+ export type FileProcessingExtraction = {
63
+ state: 'indexed' | 'partial' | 'failed' | 'skipped' | 'pending' | 'name_only';
64
+ reason?: string;
65
+ hint?: string;
66
+ pages?: { read: number; total: number };
67
+ };
68
+
69
+ /** One item made from the file (its `data.sourceFileId`): an extracted
70
+ * image (`file`), an auto Table (`table`), a page or a note from
71
+ * page_from_file / note_from_file. Only items the caller reads. */
72
+ export type FileDerivedItem = {
73
+ id: string;
74
+ /** The node type: 'file' | 'table' | 'page' | 'note' (another type is
75
+ * possible, shown as is). */
76
+ kind: string;
77
+ title: string;
78
+ /** Where it lives: the ltree path of its folder or parent. */
79
+ path: string;
80
+ };
81
+
82
+ export type FileProcessing = {
83
+ file: {
84
+ id: string;
85
+ filename: string;
86
+ extension: string;
87
+ mimeType: string;
88
+ sizeBytes: number;
89
+ sha256: string | null;
90
+ /** Its folder (ltree path). */
91
+ parentPath: string;
92
+ createdAt: string;
93
+ updatedAt: string;
94
+ };
95
+ status: FileStatus;
96
+ extraction: FileProcessingExtraction;
97
+ /** When the last read ended (ISO); null when it has not been read. */
98
+ readAt: string | null;
99
+ /** The mode of the last read: 'full', 'metadata' (name only) or 'local'
100
+ * (read on the box with no model); null before the first read. 'full'
101
+ * is the indexing mode (the content was read, not the name only), not
102
+ * that every page was: a scan read in part is `extraction.state`
103
+ * 'partial' with `extraction.pages`. */
104
+ readMode: 'full' | 'metadata' | 'local' | null;
105
+ /** The pages of the file when the brain knows them (a scan's count);
106
+ * null otherwise. */
107
+ pages: number | null;
108
+ /** Characters of text read from the file into the brain. */
109
+ textChars: number;
110
+ /** A summary of the file was written. */
111
+ summarized: boolean;
112
+ /** The file's own vector is there: it is found by meaning in search. */
113
+ embedded: boolean;
114
+ /** Text chunks of the file in search. */
115
+ chunks: number;
116
+ /** Facts taken from the file that are true now (a replaced fact is not
117
+ * counted). */
118
+ facts: number;
119
+ /** Entity mentions found in the file; null when they are not counted for
120
+ * this caller (entity edges are read in an Admin scope only). */
121
+ mentions: number | null;
122
+ /** The file's database, for a file with a Data view; null otherwise.
123
+ * `readBy`: the pipeline and version that built it (null before stamps
124
+ * or when not built). `tables`: what it extracted, each tab and its
125
+ * rows; only when built and readable by the caller (as the Data view). */
126
+ database: {
127
+ state: DataFileState;
128
+ bytes: number | null;
129
+ readBy: FileDatabaseReadBy | null;
130
+ tables?: Array<{ name: string; rows: number }>;
131
+ } | null;
132
+ /** An extract job in the queue now, or null. */
133
+ job: FileJob | null;
134
+ /** true: read by an older reader or pipeline version than the box has
135
+ * now (FileStatus.stale); false: by the current ones; null: unknown (no
136
+ * stamp: read before the stamps, or not read). */
137
+ stale: boolean | null;
138
+ /** The core reader that read the text, its version then, and the
139
+ * version in force (`current` null: no longer a known reader). Null
140
+ * with no stamp. */
141
+ readBy: { reader: string; version: number; current: number | null } | null;
142
+ /** The Reader pipeline that built the database, its version then, and
143
+ * the installed one (`current` null: not installed now). Null with no
144
+ * stamp. */
145
+ pipelineRead: { id: string; name: string; version: string; current: string | null } | null;
146
+ /** Why the read failed or was skipped (the extractor's word and a
147
+ * sentence for a person); null when nothing went wrong. */
148
+ error: { reason: string; hint: string | null } | null;
149
+ /** Images found in the file and kept as their own files, when the reader
150
+ * counted them; null otherwise. */
151
+ images: { kept: number; found: number } | null;
152
+ /** Where the content went: the items made from the file, by kind then
153
+ * title, at most FILE_DERIVED_MAX. `truncated`: there are more. */
154
+ derived: { items: FileDerivedItem[]; truncated: boolean };
155
+ };
156
+
157
+ /** The most derived items one processing answer lists. */
158
+ export const FILE_DERIVED_MAX = 200;
159
+
160
+ /** The most files one reindex call takes. */
161
+ export const FILE_REINDEX_MAX = 200;
162
+
163
+ /** POST /api/files/reindex: the files to read again, 1 to FILE_REINDEX_MAX. */
164
+ export type FileReindexBody = { ids: string[] };
165
+
166
+ /** Why a file of a reindex call was not queued:
167
+ * - `not-found`: no such file, or the caller cannot read it;
168
+ * - `not-allowed`: the caller reads it but may not change it;
169
+ * - `in-queue`: a read of it is already queued or running;
170
+ * - `busy`: the read queue is busy; nothing was queued, try again later;
171
+ * - `bytes-missing`: the file's bytes could not be read now (gone from
172
+ * disk and object store, or the store unreachable): nothing it has was
173
+ * dropped; try again when the store is back. */
174
+ export type FileReindexSkip = 'not-found' | 'not-allowed' | 'in-queue' | 'busy' | 'bytes-missing';
175
+
176
+ /** The answer of a reindex: every id sent is counted in `queued` or named
177
+ * once in `skipped`. `databases`: of the queued files, those whose
178
+ * database Reader run was queued too. */
179
+ export type FileReindexAnswer = {
180
+ queued: number;
181
+ databases: number;
182
+ skipped: Array<{ id: string; reason: FileReindexSkip }>;
183
+ };
184
+
185
+ /** The lists of GET /api/files/stale (`state`): read by an older reader or
186
+ * pipeline (`stale`), not read (`failed`), read in part (`partial`). */
187
+ export type FileStaleState = 'stale' | 'failed' | 'partial';
188
+
189
+ /** The most rows one page of GET /api/files/stale gives. */
190
+ export const FILE_STALE_MAX = 200;
191
+
192
+ /** GET /api/files/stale: one page, newest first. `files` are the file rows
193
+ * of GET /api/files/files (the client's FileRow, with `status`); `next`
194
+ * is the cursor of the next page (null: the last); `total` counts every
195
+ * file in the state the caller reads. */
196
+ export type FileStaleAnswer<Row = { id: string; status: FileStatus }> = {
197
+ files: Row[];
198
+ next: string | null;
199
+ total: number;
200
+ };
package/src/index.ts CHANGED
@@ -156,6 +156,16 @@ export type {
156
156
  FileDeleteRefusalReason,
157
157
  FileDerivedCounts,
158
158
  } from './dto/file-deletes';
159
+ export type {
160
+ FileHistoryResponse,
161
+ FileHistoryRights,
162
+ FileRestoreResponse,
163
+ FileVersion,
164
+ FileVersionTrigger,
165
+ UploadClashResponse,
166
+ UploadExistingFile,
167
+ UploadSkippedResponse,
168
+ } from './dto/file-history';
159
169
  export type {
160
170
  DataFileRow,
161
171
  DataFileState,
@@ -164,6 +174,23 @@ export type {
164
174
  FileDatabaseResponse,
165
175
  FileDatabaseTab,
166
176
  } from './dto/file-databases';
177
+ export type {
178
+ FileDerivedItem,
179
+ FileIngest,
180
+ FileJob,
181
+ FileProcessing,
182
+ FileProcessingExtraction,
183
+ FileStatus,
184
+ FileReadBy,
185
+ FilePipelineRead,
186
+ FileReindexBody,
187
+ FileReindexSkip,
188
+ FileReindexAnswer,
189
+ FileStaleState,
190
+ FileStaleAnswer,
191
+ } from './dto/file-status';
192
+ export { FILE_DERIVED_MAX } from './dto/file-status';
193
+ export { FILE_REINDEX_MAX, FILE_STALE_MAX } from './dto/file-status';
167
194
  export type {
168
195
  PipelineList,
169
196
  PipelineOptionSpec,
package/src/tree.ts CHANGED
@@ -15,6 +15,7 @@ import type { AccessLevel } from './dto/access';
15
15
  import type { GrantWorkspaceRef, ListWorkspace } from './dto/grants';
16
16
  import type { TaskStatus } from './dto/rows';
17
17
  import type { ElsewhereCount, HitWorkspaceField } from './dto/workspace-hits';
18
+ import type { FileStatus } from './dto/file-status';
18
19
  import type { AppTint } from './app-nav';
19
20
  import {
20
21
  ITEM_KINDS,
@@ -175,11 +176,18 @@ export type TreeItem = {
175
176
  state: TreeItemState | null;
176
177
  updatedAt: string;
177
178
  meta?: TreeItemMeta;
179
+ /** A file's compact status (the corner badge of its icon): was it read
180
+ * into the brain, a job in the queue, its database (dto/file-status).
181
+ * Files only; absent on every other kind, and from a brain before it. */
182
+ status?: FileStatus;
178
183
  /** The workspaces that read the item (ListChips): filled by the owner's
179
184
  * tree routes. */
180
185
  workspaces: ListWorkspace[];
181
186
  /** A live open public link exists (the "Public" pill). */
182
187
  hasLink: boolean;
188
+ /** A file only: how many kept versions it has (file history; 0 for
189
+ * none), for a history badge. */
190
+ versions?: number;
183
191
  /** A member's tree only: a draft rather than a brain item (folder plan
184
192
  * phase 5). `own` is the member's own; `team` a teammate's draft shared
185
193
  * with the team. Absent on a brain item. */