wflow-api 0.1.0__py3-none-any.whl
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.
- wflow_api/__init__.py +20 -0
- wflow_api/auth.py +85 -0
- wflow_api/client.py +130 -0
- wflow_api/errors.py +13 -0
- wflow_api/guards.py +132 -0
- wflow_api/models/__init__.py +128 -0
- wflow_api/models/account.py +127 -0
- wflow_api/models/admin.py +98 -0
- wflow_api/models/common.py +117 -0
- wflow_api/models/documents.py +514 -0
- wflow_api/models/registers.py +165 -0
- wflow_api/models/requests.py +341 -0
- wflow_api/models/storage.py +38 -0
- wflow_api/operation.py +50 -0
- wflow_api/operations/__init__.py +21 -0
- wflow_api/operations/account.py +46 -0
- wflow_api/operations/admin.py +307 -0
- wflow_api/operations/approvals.py +235 -0
- wflow_api/operations/document_files.py +145 -0
- wflow_api/operations/document_properties.py +204 -0
- wflow_api/operations/document_tags.py +60 -0
- wflow_api/operations/documents.py +603 -0
- wflow_api/operations/integrations.py +63 -0
- wflow_api/operations/organization.py +51 -0
- wflow_api/operations/registers.py +2273 -0
- wflow_api/operations/storage_files.py +477 -0
- wflow_api/operations/storage_folders.py +132 -0
- wflow_api/operations/webhooks.py +67 -0
- wflow_api/py.typed +0 -0
- wflow_api-0.1.0.dist-info/METADATA +48 -0
- wflow_api-0.1.0.dist-info/RECORD +33 -0
- wflow_api-0.1.0.dist-info/WHEEL +4 -0
- wflow_api-0.1.0.dist-info/licenses/LICENSE +202 -0
|
@@ -0,0 +1,477 @@
|
|
|
1
|
+
"""StorageFiles tag: the document archive, separate from approval documents."""
|
|
2
|
+
|
|
3
|
+
from typing import Annotated
|
|
4
|
+
|
|
5
|
+
from pydantic import Field
|
|
6
|
+
|
|
7
|
+
from wflow_api.client import WflowClient
|
|
8
|
+
from wflow_api.guards import path_segment, query_params, write_definitions_json, write_json, write_json_list
|
|
9
|
+
from wflow_api.models import (
|
|
10
|
+
OrgSlug,
|
|
11
|
+
Page,
|
|
12
|
+
Paged,
|
|
13
|
+
PageSize,
|
|
14
|
+
PropertyUpdate,
|
|
15
|
+
Query,
|
|
16
|
+
Sort,
|
|
17
|
+
StorageFile,
|
|
18
|
+
TeamBase,
|
|
19
|
+
WriteResult,
|
|
20
|
+
)
|
|
21
|
+
from wflow_api.models.common import FileContent
|
|
22
|
+
from wflow_api.models.documents import Property, PropertyDefinition
|
|
23
|
+
from wflow_api.operation import operation
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@operation
|
|
27
|
+
async def list_storage_files(
|
|
28
|
+
client: WflowClient,
|
|
29
|
+
organization: OrgSlug,
|
|
30
|
+
sort: Sort = None,
|
|
31
|
+
query: Query = None,
|
|
32
|
+
pageSize: PageSize = None,
|
|
33
|
+
page: Page = None,
|
|
34
|
+
) -> Paged[StorageFile]:
|
|
35
|
+
"""Files in the workspace's document storage — its archive, organised into folders.
|
|
36
|
+
|
|
37
|
+
Storage is separate from approval documents, which `list_documents` returns: a
|
|
38
|
+
contract or a certificate lives here, an invoice going through approval lives there.
|
|
39
|
+
If the user asks about invoices or approvals, this is the wrong operation. Note there
|
|
40
|
+
is no `search` argument on this endpoint. Removed files are
|
|
41
|
+
not returned and cannot be filtered for; note a file's id before deleting it if it may
|
|
42
|
+
need `restore_storage_file`.
|
|
43
|
+
|
|
44
|
+
Fields:
|
|
45
|
+
|
|
46
|
+
- `id` — pass to `get_storage_file` and `download_storage_file`
|
|
47
|
+
- `name`, `description` — how the file is labelled
|
|
48
|
+
- `locked` — whether it is checked out and cannot be changed
|
|
49
|
+
- `approvalStatus` — NotApproved, Approved, Rejected, Returned or None
|
|
50
|
+
- `folderId` — the folder it lives in
|
|
51
|
+
- `location` — where it is stored
|
|
52
|
+
- `removed` — the date it was removed, when it has been
|
|
53
|
+
- `created`, `updated` — when it was archived and last touched
|
|
54
|
+
"""
|
|
55
|
+
payload = await client.request(
|
|
56
|
+
"GET",
|
|
57
|
+
f"/api/{organization}/storage/files",
|
|
58
|
+
params=query_params(sort=sort, query=query, pageSize=pageSize, page=page),
|
|
59
|
+
)
|
|
60
|
+
return Paged[StorageFile].model_validate(payload or {})
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@operation
|
|
64
|
+
async def get_storage_file(client: WflowClient, organization: OrgSlug, fileId: str) -> StorageFile:
|
|
65
|
+
"""One archived file in full, by its storage file id.
|
|
66
|
+
|
|
67
|
+
Get the id from `list_storage_files`.
|
|
68
|
+
|
|
69
|
+
Fields: see `list_storage_files`.
|
|
70
|
+
"""
|
|
71
|
+
payload = await client.request("GET", f"/api/{organization}/storage/files/{path_segment(fileId)}") or {}
|
|
72
|
+
return StorageFile.model_validate(payload)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
@operation
|
|
76
|
+
async def download_storage_file(
|
|
77
|
+
client: WflowClient, organization: OrgSlug, fileId: str, *, max_bytes: int | None = None
|
|
78
|
+
) -> FileContent:
|
|
79
|
+
"""Download one archived file's content, by its storage file id.
|
|
80
|
+
|
|
81
|
+
Get the id from `list_storage_files`. For a file attached to an approval document,
|
|
82
|
+
use `download_document_file` instead.
|
|
83
|
+
|
|
84
|
+
Fields:
|
|
85
|
+
|
|
86
|
+
- `filename` — as wflow reports it, or null when it sends no name
|
|
87
|
+
- `content_type` — MIME type, e.g. "application/pdf"
|
|
88
|
+
- `content` — the file's bytes, exactly as wflow stores them
|
|
89
|
+
|
|
90
|
+
`max_bytes`, when given, refuses a larger file before it is read in full; without it
|
|
91
|
+
any size comes through.
|
|
92
|
+
"""
|
|
93
|
+
return await client.download(
|
|
94
|
+
f"/api/{organization}/storage/files/{path_segment(fileId)}/download", max_bytes=max_bytes
|
|
95
|
+
)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
@operation
|
|
99
|
+
async def get_storage_file_properties(client: WflowClient, organization: OrgSlug, fileId: str) -> list[Property]:
|
|
100
|
+
"""The custom property values set on one archived file.
|
|
101
|
+
|
|
102
|
+
A workspace defines its custom properties once with
|
|
103
|
+
`list_storage_file_property_definitions`; this is what a specific file holds for
|
|
104
|
+
each of them.
|
|
105
|
+
|
|
106
|
+
Fields:
|
|
107
|
+
|
|
108
|
+
- `name`, `type` — the definition this value belongs to
|
|
109
|
+
- `value` — what this file holds for the property
|
|
110
|
+
- `order`, `show`, `editable`, `kinds` — the definition's own presentation and
|
|
111
|
+
applicability settings, echoed alongside the value
|
|
112
|
+
"""
|
|
113
|
+
payload = await client.request("GET", f"/api/{organization}/storage/files/{path_segment(fileId)}/properties") or []
|
|
114
|
+
return [Property.model_validate(item) for item in payload]
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
@operation
|
|
118
|
+
async def get_storage_file_property_definition(
|
|
119
|
+
client: WflowClient, organization: OrgSlug, id: str
|
|
120
|
+
) -> PropertyDefinition:
|
|
121
|
+
"""One custom property definition for archived files, by its id.
|
|
122
|
+
|
|
123
|
+
Use `list_storage_file_property_definitions` to find the id, or resolve one already
|
|
124
|
+
seen on a file's `get_storage_file_properties` result.
|
|
125
|
+
|
|
126
|
+
Fields:
|
|
127
|
+
|
|
128
|
+
- `name`, `type` — how the property is labelled and what kind of value it holds
|
|
129
|
+
- `order`, `show` — where it appears, and whether it is shown at all
|
|
130
|
+
- `editable` — whether a file's value for it can be changed
|
|
131
|
+
- `kinds` — which document kinds it applies to
|
|
132
|
+
"""
|
|
133
|
+
payload = (
|
|
134
|
+
await client.request("GET", f"/api/{organization}/storage/files/properties/definition/{path_segment(id)}") or {}
|
|
135
|
+
)
|
|
136
|
+
return PropertyDefinition.model_validate(payload)
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
@operation
|
|
140
|
+
async def list_storage_file_property_definitions(
|
|
141
|
+
client: WflowClient, organization: OrgSlug
|
|
142
|
+
) -> list[PropertyDefinition]:
|
|
143
|
+
"""Every custom property defined for archived files in the workspace.
|
|
144
|
+
|
|
145
|
+
Call this to learn what custom fields exist before reading or interpreting the
|
|
146
|
+
values `get_storage_file_properties` returns for a specific file.
|
|
147
|
+
|
|
148
|
+
Fields:
|
|
149
|
+
|
|
150
|
+
- `name`, `type` — how the property is labelled and what kind of value it holds
|
|
151
|
+
- `order`, `show` — where it appears, and whether it is shown at all
|
|
152
|
+
- `editable` — whether a file's value for it can be changed
|
|
153
|
+
- `kinds` — which document kinds it applies to
|
|
154
|
+
"""
|
|
155
|
+
payload = await client.request("GET", f"/api/{organization}/storage/files/properties/definitions") or []
|
|
156
|
+
return [PropertyDefinition.model_validate(item) for item in payload]
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
@operation
|
|
160
|
+
async def get_storage_file_rights(client: WflowClient, organization: OrgSlug, fileId: str) -> list[TeamBase]:
|
|
161
|
+
"""The teams allowed to see and act on one archived file.
|
|
162
|
+
|
|
163
|
+
Fields:
|
|
164
|
+
|
|
165
|
+
- `name`, `description` — the team as shown in wflow
|
|
166
|
+
- `system` — true for a built-in team rather than one the organization created
|
|
167
|
+
"""
|
|
168
|
+
payload = await client.request("GET", f"/api/{organization}/storage/files/{path_segment(fileId)}/rights") or []
|
|
169
|
+
return [TeamBase.model_validate(item) for item in payload]
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
@operation
|
|
173
|
+
async def delete_storage_file(client: WflowClient, organization: OrgSlug, fileId: str) -> WriteResult:
|
|
174
|
+
"""Delete one archived file.
|
|
175
|
+
|
|
176
|
+
This is the archive, not the approval documents: for a file attached to a document,
|
|
177
|
+
use `delete_document_file`. Get the id from
|
|
178
|
+
`list_storage_files`. `restore_storage_file` brings the file back only by this id, and
|
|
179
|
+
once deleted it no longer appears in `list_storage_files` and `get_storage_file`
|
|
180
|
+
answers a record of nulls for it, so keep the id if it may need restoring.
|
|
181
|
+
|
|
182
|
+
Fields: on the result —
|
|
183
|
+
|
|
184
|
+
- `action` — "deleted"
|
|
185
|
+
- `resource` — "storage/files"
|
|
186
|
+
"""
|
|
187
|
+
await client.request("DELETE", f"/api/{organization}/storage/files/{path_segment(fileId)}")
|
|
188
|
+
return WriteResult(action="deleted", resource="storage/files")
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
@operation
|
|
192
|
+
async def delete_storage_file_property(
|
|
193
|
+
client: WflowClient, organization: OrgSlug, fileId: str, propertyId: str
|
|
194
|
+
) -> WriteResult:
|
|
195
|
+
"""Clear one custom property value from one archived file.
|
|
196
|
+
|
|
197
|
+
Only this file's value goes; the definition stays and every other file keeps its own
|
|
198
|
+
value. Get `propertyId` from the `id` of the entry in `get_storage_file_properties`.
|
|
199
|
+
|
|
200
|
+
Fields: on the result —
|
|
201
|
+
|
|
202
|
+
- `action` — "deleted"
|
|
203
|
+
- `resource` — "storage/files/properties"
|
|
204
|
+
"""
|
|
205
|
+
await client.request(
|
|
206
|
+
"DELETE", f"/api/{organization}/storage/files/{path_segment(fileId)}/properties/{path_segment(propertyId)}"
|
|
207
|
+
)
|
|
208
|
+
return WriteResult(action="deleted", resource="storage/files/properties")
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
@operation
|
|
212
|
+
async def delete_storage_file_property_definition(client: WflowClient, organization: OrgSlug, id: str) -> WriteResult:
|
|
213
|
+
"""Delete one archived-file custom property definition from the workspace.
|
|
214
|
+
|
|
215
|
+
This is the definition itself, not one file's value for it: the property stops
|
|
216
|
+
existing for every archived file at once. To clear a single file's value, use
|
|
217
|
+
`delete_storage_file_property`. Get the id from
|
|
218
|
+
`list_storage_file_property_definitions`.
|
|
219
|
+
|
|
220
|
+
Fields: on the result —
|
|
221
|
+
|
|
222
|
+
- `action` — "deleted"
|
|
223
|
+
- `resource` — "storage/files/properties/definition"
|
|
224
|
+
"""
|
|
225
|
+
await client.request("DELETE", f"/api/{organization}/storage/files/properties/definition/{path_segment(id)}")
|
|
226
|
+
return WriteResult(action="deleted", resource="storage/files/properties/definition")
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
@operation
|
|
230
|
+
async def lock_storage_file(client: WflowClient, organization: OrgSlug, fileId: str, value: bool) -> WriteResult:
|
|
231
|
+
"""Lock or unlock an archived file, so it cannot be changed while someone works on it.
|
|
232
|
+
|
|
233
|
+
Pass `value` true to lock, false to release. `list_storage_files` reports the current
|
|
234
|
+
state as `locked`. This is the archive: for a file attached to an approval document,
|
|
235
|
+
lock the document with `lock_document`.
|
|
236
|
+
|
|
237
|
+
Fields: on the result —
|
|
238
|
+
|
|
239
|
+
- `action` — "locked" or "unlocked"
|
|
240
|
+
- `resource` — "storage/files/lock"
|
|
241
|
+
"""
|
|
242
|
+
await client.request("PUT", f"/api/{organization}/storage/files/{path_segment(fileId)}/lock/{str(value).lower()}")
|
|
243
|
+
return WriteResult(action="locked" if value else "unlocked", resource="storage/files/lock")
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
@operation
|
|
247
|
+
async def move_storage_file(client: WflowClient, organization: OrgSlug, fileId: str, folderId: str) -> WriteResult:
|
|
248
|
+
"""Move an archived file into a different folder.
|
|
249
|
+
|
|
250
|
+
The file keeps its id, name and properties. Teams granted on the file itself may not
|
|
251
|
+
survive the move: read `get_storage_file_rights` before it and, if the list changed,
|
|
252
|
+
send it back with `set_storage_file_rights` after. Use `list_storage_folder_children`
|
|
253
|
+
to find the target folder's id.
|
|
254
|
+
|
|
255
|
+
Fields: on the result —
|
|
256
|
+
|
|
257
|
+
- `action` — "moved"
|
|
258
|
+
- `resource` — "storage/files"
|
|
259
|
+
"""
|
|
260
|
+
await client.request(
|
|
261
|
+
"PUT",
|
|
262
|
+
f"/api/{organization}/storage/files/{path_segment(fileId)}/move",
|
|
263
|
+
params=query_params(folderId=folderId),
|
|
264
|
+
)
|
|
265
|
+
return WriteResult(action="moved", resource="storage/files")
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
@operation
|
|
269
|
+
async def rename_storage_file(client: WflowClient, organization: OrgSlug, fileId: str, name: str) -> WriteResult:
|
|
270
|
+
"""Rename an archived file.
|
|
271
|
+
|
|
272
|
+
`name` replaces the old one outright, and wflow keeps no version history to read it
|
|
273
|
+
back from, so check `get_storage_file` first if the current name matters. Nothing
|
|
274
|
+
else about the file changes, and its id stays valid.
|
|
275
|
+
|
|
276
|
+
Fields: on the result —
|
|
277
|
+
|
|
278
|
+
- `action` — "renamed"
|
|
279
|
+
- `resource` — "storage/files"
|
|
280
|
+
"""
|
|
281
|
+
await client.request(
|
|
282
|
+
"PUT",
|
|
283
|
+
f"/api/{organization}/storage/files/{path_segment(fileId)}/rename",
|
|
284
|
+
params=query_params(name=name),
|
|
285
|
+
)
|
|
286
|
+
return WriteResult(action="renamed", resource="storage/files")
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
@operation
|
|
290
|
+
async def restore_storage_file(client: WflowClient, organization: OrgSlug, fileId: str, folderId: str) -> WriteResult:
|
|
291
|
+
"""Bring a removed file back into the archive, into the folder you name.
|
|
292
|
+
|
|
293
|
+
Removed files are not listed, so `fileId` must be the id noted before
|
|
294
|
+
`delete_storage_file` was called. This puts the file back under
|
|
295
|
+
`folderId`, which need not be the folder it was removed from. Use
|
|
296
|
+
`list_storage_folder_children` to find that id.
|
|
297
|
+
|
|
298
|
+
Fields: on the result —
|
|
299
|
+
|
|
300
|
+
- `action` — "restored"
|
|
301
|
+
- `resource` — "storage/files"
|
|
302
|
+
"""
|
|
303
|
+
await client.request(
|
|
304
|
+
"PUT",
|
|
305
|
+
f"/api/{organization}/storage/files/{path_segment(fileId)}/restore",
|
|
306
|
+
params=query_params(folderId=folderId),
|
|
307
|
+
)
|
|
308
|
+
return WriteResult(action="restored", resource="storage/files")
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
@operation
|
|
312
|
+
async def set_storage_file_rights(
|
|
313
|
+
client: WflowClient, organization: OrgSlug, fileId: str, teams: list[TeamBase]
|
|
314
|
+
) -> WriteResult:
|
|
315
|
+
"""Replace the set of teams allowed to see and act on one archived file.
|
|
316
|
+
|
|
317
|
+
The list you send becomes the file's rights, so a team you leave out loses access,
|
|
318
|
+
and an empty list leaves the file visible to nobody but full-access users.
|
|
319
|
+
`get_storage_file_rights` returns every team currently allowed, in one array — read
|
|
320
|
+
it first and send back everyone you mean to keep. A team is identified by its `id`,
|
|
321
|
+
which `list_teams` also returns.
|
|
322
|
+
|
|
323
|
+
Fields: on the result —
|
|
324
|
+
|
|
325
|
+
- `action` — "updated"
|
|
326
|
+
- `resource` — "storage/files/rights"
|
|
327
|
+
"""
|
|
328
|
+
await client.request(
|
|
329
|
+
"PUT",
|
|
330
|
+
f"/api/{organization}/storage/files/{path_segment(fileId)}/rights",
|
|
331
|
+
json=write_json_list(teams, allow_empty=True),
|
|
332
|
+
)
|
|
333
|
+
return WriteResult(action="updated", resource="storage/files/rights")
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
@operation
|
|
337
|
+
async def update_storage_file_properties(
|
|
338
|
+
client: WflowClient, organization: OrgSlug, fileId: str, properties: list[PropertyUpdate]
|
|
339
|
+
) -> WriteResult:
|
|
340
|
+
"""Replace the custom property values held on one archived file.
|
|
341
|
+
|
|
342
|
+
The list you send becomes the file's values, so a property you leave out is cleared
|
|
343
|
+
on this file. `get_storage_file_properties` returns everything it currently holds, in
|
|
344
|
+
one array — read it first and send back the `id` and `value` of every entry you mean
|
|
345
|
+
to keep, and nothing else: the read also carries each definition's name, type and
|
|
346
|
+
presentation, which this operation does not write. To set a value for a property not defined
|
|
347
|
+
yet, use `update_storage_file_properties_with_definition`.
|
|
348
|
+
|
|
349
|
+
Fields: on the result —
|
|
350
|
+
|
|
351
|
+
- `action` — "updated"
|
|
352
|
+
- `resource` — "storage/files/properties"
|
|
353
|
+
"""
|
|
354
|
+
await client.request(
|
|
355
|
+
"PUT",
|
|
356
|
+
f"/api/{organization}/storage/files/{path_segment(fileId)}/properties",
|
|
357
|
+
json=write_json_list(properties),
|
|
358
|
+
)
|
|
359
|
+
return WriteResult(action="updated", resource="storage/files/properties")
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
@operation
|
|
363
|
+
async def update_storage_file_properties_with_definition(
|
|
364
|
+
client: WflowClient,
|
|
365
|
+
organization: OrgSlug,
|
|
366
|
+
fileId: str,
|
|
367
|
+
properties: list[Property],
|
|
368
|
+
addOnly: Annotated[
|
|
369
|
+
bool | None, Field(default=None, description="Leave an existing definition alone; defaults to true")
|
|
370
|
+
] = None,
|
|
371
|
+
) -> WriteResult:
|
|
372
|
+
"""Define new custom properties and set their values on one archived file.
|
|
373
|
+
|
|
374
|
+
Every entry must carry `id`, `name`, `type` and `value`, whether the property is new to
|
|
375
|
+
the workspace or already defined: wflow refuses the whole list over an entry holding
|
|
376
|
+
only `id` and `value`, so such a list is refused here before anything is sent. An
|
|
377
|
+
already-defined property sent in full gets its value updated on this file; one you
|
|
378
|
+
leave out keeps its value. To set values without repeating definitions, use
|
|
379
|
+
`update_storage_file_properties`. `id` is a free-form string you choose; wflow keeps
|
|
380
|
+
at most 30 characters of it and drops dashes, so a GUID comes back changed — pick a
|
|
381
|
+
short plain id. A definition sent with only those four fields is created hidden and
|
|
382
|
+
read-only (`order` 0, `show` false, `editable` false) — change that with
|
|
383
|
+
`update_storage_file_property_definition`. A definition is workspace configuration, so
|
|
384
|
+
that part reaches every archived file. `addOnly` defaults to true, which leaves an
|
|
385
|
+
existing definition as it is; false rewrites it from what you send, for every file at
|
|
386
|
+
once.
|
|
387
|
+
|
|
388
|
+
Fields: on the result —
|
|
389
|
+
|
|
390
|
+
- `action` — "updated"
|
|
391
|
+
- `resource` — "storage/files/properties/withdefinition"
|
|
392
|
+
"""
|
|
393
|
+
await client.request(
|
|
394
|
+
"PUT",
|
|
395
|
+
f"/api/{organization}/storage/files/{path_segment(fileId)}/properties/withdefinition",
|
|
396
|
+
params=query_params(addOnly=addOnly),
|
|
397
|
+
json=write_definitions_json(properties, values_operation="update_storage_file_properties"),
|
|
398
|
+
)
|
|
399
|
+
return WriteResult(action="updated", resource="storage/files/properties/withdefinition")
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
@operation
|
|
403
|
+
async def update_storage_file_property_definition(
|
|
404
|
+
client: WflowClient, organization: OrgSlug, definition: PropertyDefinition
|
|
405
|
+
) -> WriteResult:
|
|
406
|
+
"""Define a custom property for archived files, or replace an existing definition.
|
|
407
|
+
|
|
408
|
+
This is workspace configuration, not one file's value: every archived file sees the
|
|
409
|
+
change at once. **`id` is required and you choose it** — a free-form string, not a
|
|
410
|
+
GUID wflow mints; a definition sent without one creates nothing. wflow keeps at most
|
|
411
|
+
30 characters of the id and drops dashes, so a GUID comes back changed — pick a short
|
|
412
|
+
plain id. The submitted object replaces the stored definition, so a field you
|
|
413
|
+
leave out can be cleared, and `kinds` and `data` are whole lists — omit a document
|
|
414
|
+
kind and the property stops applying there, omit a choice from `data` and it can no
|
|
415
|
+
longer be picked. `get_storage_file_property_definition` returns the definition in
|
|
416
|
+
full; read it first when changing one that exists.
|
|
417
|
+
|
|
418
|
+
**Neither `type` nor `kinds` is reliably stored.** A definition sent with
|
|
419
|
+
`type: "Text"` and `kinds: ["Other"]` can be accepted as a success and read back as
|
|
420
|
+
`type: "UNDEFINED"` and `kinds: null`. Read the definition back and check what landed
|
|
421
|
+
rather than trusting the write.
|
|
422
|
+
|
|
423
|
+
Fields: on the result —
|
|
424
|
+
|
|
425
|
+
- `action` — "updated"
|
|
426
|
+
- `resource` — "storage/files/properties/definition"
|
|
427
|
+
- `id` — the definition's id when wflow echoes the stored definition, otherwise `null`;
|
|
428
|
+
fall back to the `id` you sent
|
|
429
|
+
"""
|
|
430
|
+
stored = await client.request(
|
|
431
|
+
"PUT",
|
|
432
|
+
f"/api/{organization}/storage/files/properties/definition",
|
|
433
|
+
json=write_json(definition),
|
|
434
|
+
)
|
|
435
|
+
return WriteResult(
|
|
436
|
+
action="updated",
|
|
437
|
+
resource="storage/files/properties/definition",
|
|
438
|
+
id=stored.get("id") if isinstance(stored, dict) else None,
|
|
439
|
+
)
|
|
440
|
+
|
|
441
|
+
|
|
442
|
+
@operation
|
|
443
|
+
async def upload_storage_file(
|
|
444
|
+
client: WflowClient,
|
|
445
|
+
organization: OrgSlug,
|
|
446
|
+
filename: str,
|
|
447
|
+
content: bytes,
|
|
448
|
+
folderId: Annotated[str | None, Field(default=None, description="Folder to file it in; omit for the root")] = None,
|
|
449
|
+
overrideIfExists: Annotated[
|
|
450
|
+
bool | None, Field(default=None, description="Overwrite a file of the same name; defaults to false")
|
|
451
|
+
] = None,
|
|
452
|
+
) -> WriteResult:
|
|
453
|
+
"""Upload a file's bytes into the archive, under the `filename` wflow should store it as.
|
|
454
|
+
|
|
455
|
+
`folderId` picks the folder, which `list_storage_folder_children` walks. **Pass one.**
|
|
456
|
+
Omitting it does not file at the root: wflow refuses the upload, so name a folder.
|
|
457
|
+
When the folder already holds a file of that name, the default keeps both by storing
|
|
458
|
+
this one as a numbered copy — under a name you did not choose, so take the file's id
|
|
459
|
+
off the result rather than looking for it by name afterwards.
|
|
460
|
+
`overrideIfExists` true overwrites that file's content instead, and nothing here can
|
|
461
|
+
bring back what it held.
|
|
462
|
+
|
|
463
|
+
Fields: on the result —
|
|
464
|
+
|
|
465
|
+
- `action` — "created"
|
|
466
|
+
- `resource` — "storage/files"
|
|
467
|
+
- `id` — the stored file's id, which `get_storage_file` and the property and rights
|
|
468
|
+
operations all take
|
|
469
|
+
"""
|
|
470
|
+
created = await client.upload(
|
|
471
|
+
"PUT",
|
|
472
|
+
f"/api/{organization}/storage/files/upload",
|
|
473
|
+
filename,
|
|
474
|
+
content,
|
|
475
|
+
params=query_params(folderId=folderId, overrideIfExists=overrideIfExists),
|
|
476
|
+
)
|
|
477
|
+
return WriteResult(action="created", resource="storage/files", id=created)
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
"""StorageFolders tag: the archive's folder tree."""
|
|
2
|
+
|
|
3
|
+
from typing import Annotated
|
|
4
|
+
|
|
5
|
+
from pydantic import Field
|
|
6
|
+
|
|
7
|
+
from wflow_api.client import WflowClient
|
|
8
|
+
from wflow_api.guards import path_segment, query_params, write_json, write_json_list
|
|
9
|
+
from wflow_api.models import OrgSlug, StorageFolder, StorageFolderUpdate, TeamBase, WriteResult
|
|
10
|
+
from wflow_api.operation import operation
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
@operation
|
|
14
|
+
async def list_storage_folder_children(
|
|
15
|
+
client: WflowClient,
|
|
16
|
+
organization: OrgSlug,
|
|
17
|
+
folderId: Annotated[str | None, Field(default=None, description="Omit to list the root")] = None,
|
|
18
|
+
) -> list[StorageFolder]:
|
|
19
|
+
"""The folders directly inside one storage folder — one level, not the whole tree.
|
|
20
|
+
|
|
21
|
+
Omit `folderId` to start at the root, then walk down by passing the id of the folder
|
|
22
|
+
you want to open. Call it repeatedly to descend; there is no recursive listing.
|
|
23
|
+
|
|
24
|
+
Fields:
|
|
25
|
+
|
|
26
|
+
- `id` — pass back in to descend, or to `get_storage_folder` and `get_storage_folder_rights`
|
|
27
|
+
- `parentId` — the folder this one sits inside; null at the root
|
|
28
|
+
- `name` — the folder name
|
|
29
|
+
- `fullPath` — the folder's full path, so a caller can show where it sits without walking back up
|
|
30
|
+
- `hasChildren` — whether descending further will return anything
|
|
31
|
+
"""
|
|
32
|
+
payload = (
|
|
33
|
+
await client.request(
|
|
34
|
+
"GET",
|
|
35
|
+
f"/api/{organization}/storage/folders/children",
|
|
36
|
+
params=query_params(folderId=folderId),
|
|
37
|
+
)
|
|
38
|
+
or []
|
|
39
|
+
)
|
|
40
|
+
return [StorageFolder.model_validate(item) for item in payload]
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
@operation
|
|
44
|
+
async def get_storage_folder(client: WflowClient, organization: OrgSlug, folderId: str) -> StorageFolder:
|
|
45
|
+
"""One storage folder in full, by its folder id.
|
|
46
|
+
|
|
47
|
+
Get the id from `list_storage_folder_children`.
|
|
48
|
+
|
|
49
|
+
Fields: see `list_storage_folder_children`.
|
|
50
|
+
"""
|
|
51
|
+
payload = await client.request("GET", f"/api/{organization}/storage/folders/{path_segment(folderId)}") or {}
|
|
52
|
+
return StorageFolder.model_validate(payload)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@operation
|
|
56
|
+
async def get_storage_folder_rights(client: WflowClient, organization: OrgSlug, folderId: str) -> list[TeamBase]:
|
|
57
|
+
"""The teams allowed to see and act on one storage folder.
|
|
58
|
+
|
|
59
|
+
Fields:
|
|
60
|
+
|
|
61
|
+
- `name`, `description` — the team as shown in wflow
|
|
62
|
+
- `system` — true for a built-in team rather than one the organization created
|
|
63
|
+
"""
|
|
64
|
+
payload = await client.request("GET", f"/api/{organization}/storage/folders/{path_segment(folderId)}/rights") or []
|
|
65
|
+
return [TeamBase.model_validate(item) for item in payload]
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@operation
|
|
69
|
+
async def delete_storage_folder(client: WflowClient, organization: OrgSlug, folderId: str) -> WriteResult:
|
|
70
|
+
"""Delete one storage folder.
|
|
71
|
+
|
|
72
|
+
A folder holds both files and further folders, and `hasChildren` on
|
|
73
|
+
`list_storage_folder_children` only accounts for the folders. Check what is inside
|
|
74
|
+
before deleting; `list_storage_files` reports each file's `folderId`.
|
|
75
|
+
|
|
76
|
+
Fields: on the result —
|
|
77
|
+
|
|
78
|
+
- `action` — "deleted"
|
|
79
|
+
- `resource` — "storage/folders"
|
|
80
|
+
"""
|
|
81
|
+
await client.request("DELETE", f"/api/{organization}/storage/folders/{path_segment(folderId)}")
|
|
82
|
+
return WriteResult(action="deleted", resource="storage/folders")
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
@operation
|
|
86
|
+
async def set_storage_folder_rights(
|
|
87
|
+
client: WflowClient, organization: OrgSlug, folderId: str, teams: list[TeamBase]
|
|
88
|
+
) -> WriteResult:
|
|
89
|
+
"""Replace the set of teams allowed to see and act on one storage folder.
|
|
90
|
+
|
|
91
|
+
The list you send becomes the folder's rights, so a team you leave out loses access,
|
|
92
|
+
and an empty list leaves the folder visible to nobody but full-access users.
|
|
93
|
+
`get_storage_folder_rights` returns every team currently allowed, in one array — read
|
|
94
|
+
it first and send back everyone you mean to keep. A team is identified by its `id`,
|
|
95
|
+
which `list_teams` also returns.
|
|
96
|
+
|
|
97
|
+
Fields: on the result —
|
|
98
|
+
|
|
99
|
+
- `action` — "updated"
|
|
100
|
+
- `resource` — "storage/folders/rights"
|
|
101
|
+
"""
|
|
102
|
+
await client.request(
|
|
103
|
+
"PUT",
|
|
104
|
+
f"/api/{organization}/storage/folders/{path_segment(folderId)}/rights",
|
|
105
|
+
json=write_json_list(teams, allow_empty=True),
|
|
106
|
+
)
|
|
107
|
+
return WriteResult(action="updated", resource="storage/folders/rights")
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
@operation
|
|
111
|
+
async def update_storage_folder(client: WflowClient, organization: OrgSlug, folder: StorageFolderUpdate) -> WriteResult:
|
|
112
|
+
"""Create a storage folder, or replace an existing one's name and place in the tree.
|
|
113
|
+
|
|
114
|
+
Matched by the `id` inside `folder`; omit `id` to create, and omit `parentId` on a
|
|
115
|
+
new folder to put it at the root. The submitted object replaces the stored folder, so
|
|
116
|
+
send the full record when changing one that exists: a field you leave out can be
|
|
117
|
+
cleared, and for `parentId` that is the folder's place in the tree.
|
|
118
|
+
`get_storage_folder` returns what is stored today, plus a `fullPath` and `hasChildren`
|
|
119
|
+
it computes; send back the other three.
|
|
120
|
+
|
|
121
|
+
Fields: on the result —
|
|
122
|
+
|
|
123
|
+
- `action` — "updated"
|
|
124
|
+
- `resource` — "storage/folders"
|
|
125
|
+
- `id` — the folder's id
|
|
126
|
+
"""
|
|
127
|
+
created = await client.request(
|
|
128
|
+
"PUT",
|
|
129
|
+
f"/api/{organization}/storage/folders",
|
|
130
|
+
json=write_json(folder),
|
|
131
|
+
)
|
|
132
|
+
return WriteResult(action="updated", resource="storage/folders", id=created)
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""WebHookRegistrations tag: the endpoints an integrator connects to."""
|
|
2
|
+
|
|
3
|
+
from wflow_api.client import WflowClient
|
|
4
|
+
from wflow_api.guards import path_segment, write_json
|
|
5
|
+
from wflow_api.models import OrgSlug, WebHookRegistration, WriteResult
|
|
6
|
+
from wflow_api.operation import operation
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
@operation
|
|
10
|
+
async def list_webhook_registrations(client: WflowClient, organization: OrgSlug) -> list[WebHookRegistration]:
|
|
11
|
+
"""Webhook registrations configured for this workspace.
|
|
12
|
+
|
|
13
|
+
Fields:
|
|
14
|
+
|
|
15
|
+
- `id`
|
|
16
|
+
- `webHookUri` — the URL wflow calls
|
|
17
|
+
- `description`
|
|
18
|
+
- `actions` — one or more of: All, DocumentReadyToExtract, DocumentReadyToExport,
|
|
19
|
+
DocumentUpdated, DocumentApprovalProcessFinished, RegisterUpdated, DocumentDeleted,
|
|
20
|
+
DocumentReadyToReview, DocumentCreated, DocumentReviewed
|
|
21
|
+
"""
|
|
22
|
+
payload = await client.request("GET", f"/api/{organization}/webhookregistrations") or []
|
|
23
|
+
return [WebHookRegistration.model_validate(item) for item in payload]
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@operation
|
|
27
|
+
async def delete_webhook_registration(client: WflowClient, organization: OrgSlug, registrationId: str) -> WriteResult:
|
|
28
|
+
"""Delete one webhook registration, so wflow stops calling that endpoint.
|
|
29
|
+
|
|
30
|
+
Whatever is on the far end of `webHookUri` goes silent for the `actions` this
|
|
31
|
+
registration covered, with no notice to it. Get the id from
|
|
32
|
+
`list_webhook_registrations`.
|
|
33
|
+
|
|
34
|
+
Fields: on the result —
|
|
35
|
+
|
|
36
|
+
- `action` — "deleted"
|
|
37
|
+
- `resource` — "webhookregistrations"
|
|
38
|
+
"""
|
|
39
|
+
await client.request("DELETE", f"/api/{organization}/webhookregistrations/{path_segment(registrationId)}")
|
|
40
|
+
return WriteResult(action="deleted", resource="webhookregistrations")
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
@operation
|
|
44
|
+
async def update_webhook_registration(
|
|
45
|
+
client: WflowClient, organization: OrgSlug, registration: WebHookRegistration
|
|
46
|
+
) -> WriteResult:
|
|
47
|
+
"""Register a URL for wflow to call, or replace an existing registration.
|
|
48
|
+
|
|
49
|
+
Matched by the `id` inside `registration`; omit it to create. `actions` is a whole
|
|
50
|
+
set — an action you omit stops being delivered, with no notice to whatever is on the
|
|
51
|
+
far end of `webHookUri` — and send `webHookUri` and `description` with it: whether a
|
|
52
|
+
field you omit is kept or cleared is not guaranteed, so send the whole registration.
|
|
53
|
+
`list_webhook_registrations` returns every registration with its actions; read it
|
|
54
|
+
first when changing one that exists.
|
|
55
|
+
|
|
56
|
+
Fields: on the result —
|
|
57
|
+
|
|
58
|
+
- `action` — "updated"
|
|
59
|
+
- `resource` — "webhookregistrations"
|
|
60
|
+
- `id` — the registration's id
|
|
61
|
+
"""
|
|
62
|
+
created = await client.request(
|
|
63
|
+
"PUT",
|
|
64
|
+
f"/api/{organization}/webhookregistrations",
|
|
65
|
+
json=write_json(registration),
|
|
66
|
+
)
|
|
67
|
+
return WriteResult(action="updated", resource="webhookregistrations", id=created)
|
wflow_api/py.typed
ADDED
|
File without changes
|