@crossworks/client-types 0.705.1 → 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 +1 -1
- package/src/dto/file-history.ts +87 -0
- package/src/dto/file-status.ts +200 -0
- package/src/index.ts +27 -0
- package/src/tree.ts +8 -0
package/package.json
CHANGED
|
@@ -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. */
|