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.
@@ -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