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,307 @@
1
+ """Roles, Teams and Users tags: who exists in the workspace, and what they may do."""
2
+
3
+ from wflow_api.client import WflowClient
4
+ from wflow_api.guards import path_segment, query_params, write_json
5
+ from wflow_api.models import (
6
+ OrgSlug,
7
+ Page,
8
+ Paged,
9
+ PageSize,
10
+ Query,
11
+ Role,
12
+ RoleBase,
13
+ RoleUpdate,
14
+ Search,
15
+ Sort,
16
+ Team,
17
+ TeamBase,
18
+ TeamUpdate,
19
+ User,
20
+ UserFull,
21
+ UserUpdate,
22
+ WriteResult,
23
+ )
24
+ from wflow_api.operation import operation
25
+
26
+
27
+ @operation
28
+ async def list_roles(
29
+ client: WflowClient,
30
+ organization: OrgSlug,
31
+ search: Search = None,
32
+ sort: Sort = None,
33
+ query: Query = None,
34
+ pageSize: PageSize = None,
35
+ page: Page = None,
36
+ ) -> Paged[RoleBase]:
37
+ """Roles configured in the workspace — named bundles of rights assignable to users.
38
+
39
+ Fields:
40
+
41
+ - `id` — pass to `get_role`
42
+ - `name`, `description`
43
+ """
44
+ payload = await client.request(
45
+ "GET",
46
+ f"/api/{organization}/roles",
47
+ params=query_params(search=search, sort=sort, query=query, pageSize=pageSize, page=page),
48
+ )
49
+ return Paged[RoleBase].model_validate(payload or {})
50
+
51
+
52
+ @operation
53
+ async def get_role(client: WflowClient, organization: OrgSlug, id: str) -> Role:
54
+ """One role in full, by its role id.
55
+
56
+ Get the id from `list_roles`.
57
+
58
+ Fields: beyond those on the list summary —
59
+
60
+ - `users` — each user holding this role, as an id and identity
61
+ - `rights` — the permission strings this role grants, e.g. CanApprove,
62
+ CanCreateDocument, CanManageSettings
63
+ """
64
+ payload = await client.request("GET", f"/api/{organization}/roles/{path_segment(id)}") or {}
65
+ return Role.model_validate(payload)
66
+
67
+
68
+ @operation
69
+ async def list_teams(
70
+ client: WflowClient,
71
+ organization: OrgSlug,
72
+ search: Search = None,
73
+ sort: Sort = None,
74
+ query: Query = None,
75
+ pageSize: PageSize = None,
76
+ page: Page = None,
77
+ ) -> Paged[TeamBase]:
78
+ """Teams configured in the workspace — groups of users assignable to approval steps.
79
+
80
+ Fields:
81
+
82
+ - `id` — pass to `get_team`
83
+ - `name`, `description`
84
+ - `system` — true for a built-in team rather than one the organization created
85
+ """
86
+ payload = await client.request(
87
+ "GET",
88
+ f"/api/{organization}/teams",
89
+ params=query_params(search=search, sort=sort, query=query, pageSize=pageSize, page=page),
90
+ )
91
+ return Paged[TeamBase].model_validate(payload or {})
92
+
93
+
94
+ @operation
95
+ async def get_team(client: WflowClient, organization: OrgSlug, id: str) -> Team:
96
+ """One team in full, by its team id.
97
+
98
+ Get the id from `list_teams`.
99
+
100
+ Fields: beyond those on the list summary —
101
+
102
+ - `users` — each member, as an id and identity
103
+ """
104
+ payload = await client.request("GET", f"/api/{organization}/teams/{path_segment(id)}") or {}
105
+ return Team.model_validate(payload)
106
+
107
+
108
+ @operation
109
+ async def list_users(
110
+ client: WflowClient,
111
+ organization: OrgSlug,
112
+ search: Search = None,
113
+ sort: Sort = None,
114
+ query: Query = None,
115
+ pageSize: PageSize = None,
116
+ page: Page = None,
117
+ ) -> Paged[User]:
118
+ """The people with access to this workspace.
119
+
120
+ `get_me` answers this for the signed-in user only. Use this to see everyone, for
121
+ example to work out who can approve a document that is waiting. For one user's
122
+ role, team and per-document-type permissions, follow up with `get_user`.
123
+
124
+ Fields:
125
+
126
+ - `id` — pass to `get_user`
127
+ - `identity` — login, first/last/full name and preferred language
128
+ - `created` — when the account was created
129
+ - `hasFullAccess` — full-access role indicator, which overrides per-type detail
130
+ """
131
+ payload = await client.request(
132
+ "GET",
133
+ f"/api/{organization}/users",
134
+ params=query_params(search=search, sort=sort, query=query, pageSize=pageSize, page=page),
135
+ )
136
+ return Paged[User].model_validate(payload or {})
137
+
138
+
139
+ @operation
140
+ async def get_user(client: WflowClient, organization: OrgSlug, userId: str) -> UserFull:
141
+ """One user in full, by their user id.
142
+
143
+ Get the id from `list_users`. Same shape `get_me` returns for the signed-in user.
144
+
145
+ Fields: beyond those on the list summary —
146
+
147
+ - `roles`, `teams` — memberships
148
+ - `documentTypes` — per document type: All, OnlyAssigned or FullAccess
149
+ - `rights` — named rights held here, e.g. CanApprove, CanCreateDocument
150
+ """
151
+ payload = await client.request("GET", f"/api/{organization}/users/{path_segment(userId)}") or {}
152
+ return UserFull.model_validate(payload)
153
+
154
+
155
+ @operation
156
+ async def delete_role(client: WflowClient, organization: OrgSlug, id: str) -> WriteResult:
157
+ """Delete one role from the workspace.
158
+
159
+ A role carries rights and holders. `get_role` lists both — read it first, because
160
+ everyone under `users` loses what the role granted them.
161
+
162
+ Fields: on the result —
163
+
164
+ - `action` — "deleted"
165
+ - `resource` — "roles"
166
+ """
167
+ await client.request("DELETE", f"/api/{organization}/roles/{path_segment(id)}")
168
+ return WriteResult(action="deleted", resource="roles")
169
+
170
+
171
+ @operation
172
+ async def delete_team(client: WflowClient, organization: OrgSlug, id: str) -> WriteResult:
173
+ """Delete one team from the workspace.
174
+
175
+ Teams are what approval templates and document rights are assigned to, so a team in
176
+ use is referenced well beyond its own record. `get_team` lists its members; system
177
+ teams, flagged `system` by `list_teams`, are wflow's own rather than the
178
+ organization's.
179
+
180
+ Fields: on the result —
181
+
182
+ - `action` — "deleted"
183
+ - `resource` — "teams"
184
+ """
185
+ await client.request("DELETE", f"/api/{organization}/teams/{path_segment(id)}")
186
+ return WriteResult(action="deleted", resource="teams")
187
+
188
+
189
+ @operation
190
+ async def delete_user(client: WflowClient, organization: OrgSlug, userId: str) -> WriteResult:
191
+ """Remove one person's access to this workspace.
192
+
193
+ Get the id from `list_users`; `get_user` shows the roles, teams and document-type
194
+ permissions that go with them, which is what this takes away.
195
+
196
+ Fields: on the result —
197
+
198
+ - `action` — "deleted"
199
+ - `resource` — "users"
200
+ """
201
+ await client.request("DELETE", f"/api/{organization}/users/{path_segment(userId)}")
202
+ return WriteResult(action="deleted", resource="users")
203
+
204
+
205
+ @operation
206
+ async def create_role(client: WflowClient, organization: OrgSlug, role: RoleUpdate) -> WriteResult:
207
+ """Create a role — a named bundle of rights that users and teams can be given.
208
+
209
+ Use `list_roles` first to check the name is not already taken; this creates rather
210
+ than upserts, so a duplicate name gives you two roles that look alike. `users` is a
211
+ list of user ids, from `list_users`.
212
+
213
+ Fields: on the result —
214
+
215
+ - `action` — "created"
216
+ - `resource` — "roles"
217
+ - `id` — the new role's id
218
+ """
219
+ created = await client.request("POST", f"/api/{organization}/roles", json=write_json(role))
220
+ return WriteResult(action="created", resource="roles", id=created)
221
+
222
+
223
+ @operation
224
+ async def create_team(client: WflowClient, organization: OrgSlug, team: TeamUpdate) -> WriteResult:
225
+ """Create a team — the group approval steps and document rights are assigned to.
226
+
227
+ Use `list_teams` first to check the name is not already taken; this creates rather
228
+ than upserts, so a duplicate name gives you two teams that look alike. `users` is a
229
+ list of user ids, from `list_users`.
230
+
231
+ Fields: on the result —
232
+
233
+ - `action` — "created"
234
+ - `resource` — "teams"
235
+ - `id` — the new team's id
236
+ """
237
+ created = await client.request("POST", f"/api/{organization}/teams", json=write_json(team))
238
+ return WriteResult(action="created", resource="teams", id=created)
239
+
240
+
241
+ @operation
242
+ async def update_role(client: WflowClient, organization: OrgSlug, id: str, role: RoleUpdate) -> WriteResult:
243
+ """Replace one role's name, description, holders and rights.
244
+
245
+ The submitted object replaces the stored role, so a field you leave out can be
246
+ cleared. `users` and `rights` are whole sets: a holder you omit loses the role, and a
247
+ right you omit is taken off everyone who holds it. `get_role` returns both lists in
248
+ full — read it first and send back everything you mean to keep, `users` as the `id` of
249
+ each holder it lists. Get the role id from `list_roles`.
250
+
251
+ Fields: on the result —
252
+
253
+ - `action` — "updated"
254
+ - `resource` — "roles"
255
+ - `id` — the role's id
256
+ """
257
+ updated = await client.request("PUT", f"/api/{organization}/roles/{path_segment(id)}", json=write_json(role))
258
+ return WriteResult(action="updated", resource="roles", id=updated)
259
+
260
+
261
+ @operation
262
+ async def update_team(client: WflowClient, organization: OrgSlug, id: str, team: TeamUpdate) -> WriteResult:
263
+ """Replace one team's name, description and membership.
264
+
265
+ Send the name and description along with the membership: a `description` you leave
266
+ out is cleared, not kept, so the full record is the only correct payload. `users` is a
267
+ whole set: a member you omit is removed from the team, and with it from every
268
+ approval step and document right the team carries. `get_team` returns the membership
269
+ in full — read it first and send back everyone you mean to keep, as the `id` of each
270
+ member it lists. Get the team id from `list_teams`.
271
+
272
+ Fields: on the result —
273
+
274
+ - `action` — "updated"
275
+ - `resource` — "teams"
276
+ - `id` — the team's id
277
+ """
278
+ updated = await client.request("PUT", f"/api/{organization}/teams/{path_segment(id)}", json=write_json(team))
279
+ return WriteResult(action="updated", resource="teams", id=updated)
280
+
281
+
282
+ @operation
283
+ async def update_user(client: WflowClient, organization: OrgSlug, user: UserUpdate) -> WriteResult:
284
+ """Add a person to this workspace, or replace what an existing person may do.
285
+
286
+ The person is matched by `login`: if no one in this workspace has it, they are added;
287
+ if someone does, their record is replaced by what you send. Either way the result says
288
+ `"updated"`, so it does not tell you which happened — call `get_user` or `list_users`
289
+ first if that matters.
290
+
291
+ `roles`, `teams` and `documentTypes` are whole sets: a membership you leave out is taken
292
+ away, and omitting `documentTypes` can leave the person able to see nothing. Send the
293
+ rest of the record too: whether a field you omit is kept or cleared is not guaranteed.
294
+
295
+ To change an existing person, read them with `get_user` first and send back everything
296
+ you mean to keep. It returns the same data in its own shape: `roles` and `teams` are
297
+ `{"id": …}` references, `documentTypes` is `{"id": …, "permission": …}`, and `login`
298
+ is the one inside its `identity`.
299
+
300
+ Fields: on the result —
301
+
302
+ - `action` — "updated", whether the person was added or changed
303
+ - `resource` — "users"
304
+ - `id` — the user's id
305
+ """
306
+ updated = await client.request("PUT", f"/api/{organization}/users", json=write_json(user))
307
+ return WriteResult(action="updated", resource="users", id=updated)
@@ -0,0 +1,235 @@
1
+ """DocumentApprovals and ApprovalsTemplates tags: approval workflows and the templates they run."""
2
+
3
+ from wflow_api.client import WflowClient
4
+ from wflow_api.guards import path_segment, query_params, write_json
5
+ from wflow_api.models import (
6
+ ApprovalsTemplate,
7
+ ApprovalsTemplateFull,
8
+ ApprovalsTemplateTeams,
9
+ ApprovalsTemplateUpdate,
10
+ OrgSlug,
11
+ Page,
12
+ Paged,
13
+ PageSize,
14
+ Query,
15
+ Search,
16
+ Sort,
17
+ WriteResult,
18
+ )
19
+ from wflow_api.models.documents import ApprovalProcess
20
+ from wflow_api.operation import operation
21
+
22
+
23
+ @operation
24
+ async def get_document_approvals(client: WflowClient, organization: OrgSlug, documentId: str) -> ApprovalProcess:
25
+ """The approval path assigned to one document, and its progress so far.
26
+
27
+ Fields:
28
+
29
+ - `pathName` — the name of the approval template applied
30
+ - `items` — one entry per level, each with the assigned `team` or `identity`,
31
+ its `status` (NotApproved, Approved, Rejected, Returned or None) and, once
32
+ acted on, the `date`
33
+ """
34
+ return ApprovalProcess.model_validate(
35
+ await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/approvals") or {}
36
+ )
37
+
38
+
39
+ @operation
40
+ async def get_storage_file_approvals(client: WflowClient, organization: OrgSlug, fileId: str) -> ApprovalProcess:
41
+ """The approval path assigned to one archived file, and its progress so far.
42
+
43
+ Same shape as `get_document_approvals`, for a storage file instead of an approval
44
+ document. Get the id from `list_storage_files`.
45
+
46
+ Fields: see `get_document_approvals`.
47
+ """
48
+ return ApprovalProcess.model_validate(
49
+ await client.request("GET", f"/api/{organization}/storage/files/{path_segment(fileId)}/approvals") or {}
50
+ )
51
+
52
+
53
+ @operation
54
+ async def list_approval_templates(
55
+ client: WflowClient,
56
+ organization: OrgSlug,
57
+ search: Search = None,
58
+ sort: Sort = None,
59
+ query: Query = None,
60
+ pageSize: PageSize = None,
61
+ page: Page = None,
62
+ ) -> Paged[ApprovalsTemplate]:
63
+ """Approval templates configured in the workspace — the approval paths documents follow.
64
+
65
+ Fields:
66
+
67
+ - `id` — pass to `get_approval_template`
68
+ - `name`
69
+ - `isEmpty` — true when the template defines no approval steps
70
+ """
71
+ payload = await client.request(
72
+ "GET",
73
+ f"/api/{organization}/approvalstemplates",
74
+ params=query_params(search=search, sort=sort, query=query, pageSize=pageSize, page=page),
75
+ )
76
+ return Paged[ApprovalsTemplate].model_validate(payload or {})
77
+
78
+
79
+ @operation
80
+ async def get_approval_template(client: WflowClient, organization: OrgSlug, templateId: str) -> ApprovalsTemplateFull:
81
+ """One approval template in full, by its template id.
82
+
83
+ Get the id from `list_approval_templates`.
84
+
85
+ Fields: beyond those on the list summary —
86
+
87
+ - `teams` — each assigned team's id and its `level` in the approval process
88
+ - `accessTeams` — team ids granted access automatically once the template applies
89
+ - `conditionFolders` — storage folder ids this template's conditional assignment
90
+ applies to
91
+ - `validationLockLevel`
92
+ """
93
+ payload = await client.request("GET", f"/api/{organization}/approvalstemplates/{path_segment(templateId)}") or {}
94
+ return ApprovalsTemplateFull.model_validate(payload)
95
+
96
+
97
+ @operation
98
+ async def delete_approval_template(client: WflowClient, organization: OrgSlug, templateId: str) -> WriteResult:
99
+ """Delete one approval template — an approval path the workspace can assign.
100
+
101
+ The template is workspace configuration, not one document's approval process: this
102
+ removes the path itself, for everything that would have used it. To take the path off
103
+ a single document, use `delete_document_approval_path`. Get the id from
104
+ `list_approval_templates`.
105
+
106
+ Fields: on the result —
107
+
108
+ - `action` — "deleted"
109
+ - `resource` — "approvalstemplates"
110
+ """
111
+ await client.request("DELETE", f"/api/{organization}/approvalstemplates/{path_segment(templateId)}")
112
+ return WriteResult(action="deleted", resource="approvalstemplates")
113
+
114
+
115
+ @operation
116
+ async def delete_document_approval_path(client: WflowClient, organization: OrgSlug, documentId: str) -> WriteResult:
117
+ """Take the approval path off one document.
118
+
119
+ The template it was assigned from is untouched; what goes is this document's approval
120
+ process, including the approvals already recorded on it that
121
+ `get_document_approvals` returns. The document itself stays.
122
+
123
+ Fields: on the result —
124
+
125
+ - `action` — "deleted"
126
+ - `resource` — "documents/approvals"
127
+ """
128
+ await client.request("DELETE", f"/api/{organization}/documents/{path_segment(documentId)}/approvals")
129
+ return WriteResult(action="deleted", resource="documents/approvals")
130
+
131
+
132
+ @operation
133
+ async def delete_storage_file_approval_path(client: WflowClient, organization: OrgSlug, fileId: str) -> WriteResult:
134
+ """Take the approval path off one archived file.
135
+
136
+ The same as `delete_document_approval_path`, for a storage file instead of an
137
+ approval document: the template survives, this file's approval process does not. Get
138
+ the id from `list_storage_files`.
139
+
140
+ Fields: on the result —
141
+
142
+ - `action` — "deleted"
143
+ - `resource` — "storage/files/approvals"
144
+ """
145
+ await client.request("DELETE", f"/api/{organization}/storage/files/{path_segment(fileId)}/approvals")
146
+ return WriteResult(action="deleted", resource="storage/files/approvals")
147
+
148
+
149
+ @operation
150
+ async def set_storage_file_approval_path(
151
+ client: WflowClient, organization: OrgSlug, fileId: str, templateId: str
152
+ ) -> WriteResult:
153
+ """Put one archived file through the approval path a template describes.
154
+
155
+ Get `templateId` from `list_approval_templates`; to take the path off rather than
156
+ swap it, use `delete_storage_file_approval_path`. Read `get_storage_file_approvals`
157
+ first where a process is already running: a file that already has a path may be
158
+ refused or may have its path replaced, so take the old path off with
159
+ `delete_storage_file_approval_path` first rather than relying on either outcome.
160
+
161
+ Fields: on the result —
162
+
163
+ - `action` — "set"
164
+ - `resource` — "storage/files/approvals"
165
+ """
166
+ await client.request(
167
+ "PUT", f"/api/{organization}/storage/files/{path_segment(fileId)}/approvals/set/{path_segment(templateId)}"
168
+ )
169
+ return WriteResult(action="set", resource="storage/files/approvals")
170
+
171
+
172
+ @operation
173
+ async def update_approval_template(
174
+ client: WflowClient, organization: OrgSlug, template: ApprovalsTemplateUpdate
175
+ ) -> WriteResult:
176
+ """Create an approval template, or replace an existing one's steps.
177
+
178
+ A template is workspace configuration, not one document's process: this reaches
179
+ everything the path is assigned to. Matched by the `id` inside `template`. `teams`,
180
+ `accessTeams` and `conditionFolders` are whole sets — a team you leave out is no
181
+ longer part of the path at any level — and send the rest of the template with them:
182
+ a field you omit, `validationLockLevel` included, is cleared rather than kept, so the
183
+ whole record is the only correct payload.
184
+ `get_approval_template` returns all three — read it first and send back
185
+ everything you mean to keep, leaving out its `isEmpty`, which the read computes and
186
+ this operation does not write. Each entry in `teams` is a team id from `list_teams` plus
187
+ the `level` it approves at.
188
+
189
+ Fields: on the result —
190
+
191
+ - `action` — "updated"
192
+ - `resource` — "approvalstemplates"
193
+ - `id` — the template's id
194
+ """
195
+ created = await client.request(
196
+ "PUT",
197
+ f"/api/{organization}/approvalstemplates",
198
+ json=write_json(template),
199
+ )
200
+ return WriteResult(action="updated", resource="approvalstemplates", id=created)
201
+
202
+
203
+ @operation
204
+ async def set_document_approval_path(
205
+ client: WflowClient,
206
+ organization: OrgSlug,
207
+ documentId: str,
208
+ templateId: str,
209
+ teams: ApprovalsTemplateTeams | None = None,
210
+ ) -> WriteResult:
211
+ """Put one document through the approval path a template describes.
212
+
213
+ **It does not overwrite an existing path — it refuses.** A document already on a path
214
+ is rejected with an error saying so, so swapping a path means calling
215
+ `delete_document_approval_path` first; this operation only ever sets a path on a document
216
+ that has none. Get `templateId` from `list_approval_templates`.
217
+
218
+ Omit `teams` to apply the template as it is configured: the template's own teams
219
+ appear on the document. Sent, `teams` replaces the template's assignment for this
220
+ document rather than adding to it, so name every level you mean to keep — and read
221
+ `get_document_approvals` back afterwards, because the level a team lands on is not
222
+ guaranteed to be the level you sent.
223
+
224
+ Fields: on the result —
225
+
226
+ - `action` — "set"
227
+ - `resource` — "documents/approvals"
228
+ """
229
+ # httpx sends no body for json=None; `{}` would bind as teams=null, a different instruction.
230
+ await client.request(
231
+ "PUT",
232
+ f"/api/{organization}/documents/{path_segment(documentId)}/approvals/set/{path_segment(templateId)}",
233
+ json=write_json(teams) if teams is not None else None,
234
+ )
235
+ return WriteResult(action="set", resource="documents/approvals")
@@ -0,0 +1,145 @@
1
+ """DocumentFiles tag: the files attached to a document, and their content."""
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
9
+ from wflow_api.models import OrgSlug, WriteResult
10
+ from wflow_api.models.common import FileContent
11
+ from wflow_api.models.documents import DocumentFile
12
+ from wflow_api.operation import operation
13
+
14
+
15
+ @operation
16
+ async def list_document_files(client: WflowClient, organization: OrgSlug, documentId: str) -> list[DocumentFile]:
17
+ """The files attached to one document — the scan or PDF, plus any annexes.
18
+
19
+ Call this before downloading, to find out which file you want: exactly one is the
20
+ main document and the rest are attachments.
21
+
22
+ Fields:
23
+
24
+ - `name` — the file name as stored
25
+ - `main` — true for the document's primary file; `download_document_main_file`
26
+ fetches this one without needing its id
27
+ - `signed`, `stamped` — whether wflow has applied a signature or a stamp
28
+ - `created` — when it was attached
29
+ """
30
+ payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/files") or []
31
+ return [DocumentFile.model_validate(item) for item in payload]
32
+
33
+
34
+ @operation
35
+ async def download_document_main_file(
36
+ client: WflowClient, organization: OrgSlug, documentId: str, *, max_bytes: int | None = None
37
+ ) -> FileContent:
38
+ """Download the document's primary file — the scan or PDF the document was made from.
39
+
40
+ Use this when you have a document id and want its content without first listing the
41
+ attachments. The file comes back as its own bytes, exactly as wflow stores it.
42
+
43
+ Fields:
44
+
45
+ - `filename` — as wflow reports it, or null when it sends no name
46
+ - `content_type` — MIME type, e.g. "application/pdf"
47
+ - `content` — the file's bytes
48
+
49
+ With `max_bytes` set, a larger file is refused rather than truncated. A document with no
50
+ primary file is reported as such rather than returned empty.
51
+ """
52
+ return await client.download(
53
+ f"/api/{organization}/documents/{path_segment(documentId)}/files/main/download", max_bytes=max_bytes
54
+ )
55
+
56
+
57
+ @operation
58
+ async def download_document_file(
59
+ client: WflowClient, organization: OrgSlug, fileId: str, *, max_bytes: int | None = None
60
+ ) -> FileContent:
61
+ """Download one specific file attached to a document, by its file id.
62
+
63
+ Get the id from `list_document_files`. For the primary file, `download_document_main_file`
64
+ saves a call. The file comes back as its own bytes, exactly as wflow stores it.
65
+
66
+ Fields:
67
+
68
+ - `filename` — as wflow reports it, or null when it sends no name
69
+ - `content_type` — MIME type, e.g. "application/pdf"
70
+ - `content` — the file's bytes
71
+
72
+ With `max_bytes` set, a larger file is refused rather than truncated.
73
+ """
74
+ return await client.download(
75
+ f"/api/{organization}/documents/files/{path_segment(fileId)}/download", max_bytes=max_bytes
76
+ )
77
+
78
+
79
+ @operation
80
+ async def delete_document_file(client: WflowClient, organization: OrgSlug, fileId: str) -> WriteResult:
81
+ """Delete one file attached to a document. The document itself stays.
82
+
83
+ Get the id from `list_document_files`, which also flags the file marked `main`:
84
+ deleting that one leaves the document without the scan or PDF it was made from.
85
+
86
+ Fields: on the result —
87
+
88
+ - `action` — "deleted"
89
+ - `resource` — "documents/files"
90
+ """
91
+ await client.request("DELETE", f"/api/{organization}/documents/files/{path_segment(fileId)}")
92
+ return WriteResult(action="deleted", resource="documents/files")
93
+
94
+
95
+ @operation
96
+ async def stamp_document_file(client: WflowClient, organization: OrgSlug, documentId: str, fileId: str) -> WriteResult:
97
+ """Apply wflow's time stamp to one file attached to a document.
98
+
99
+ The stamp goes into the stored file and nothing takes it off again. Only a
100
+ PDF can be stamped; any other file is rejected as an unsupported file type.
101
+ `list_document_files` reports which files already carry one as `stamped`, and a
102
+ document type can stamp automatically — `list_document_types` shows that as `autoStamp`.
103
+
104
+ Fields: on the result —
105
+
106
+ - `action` — "stamped"
107
+ - `resource` — "documents/files"
108
+ """
109
+ await client.request(
110
+ "PUT", f"/api/{organization}/documents/{path_segment(documentId)}/files/{path_segment(fileId)}/stamp"
111
+ )
112
+ return WriteResult(action="stamped", resource="documents/files")
113
+
114
+
115
+ @operation
116
+ async def upload_document_file(
117
+ client: WflowClient,
118
+ organization: OrgSlug,
119
+ documentId: str,
120
+ filename: str,
121
+ content: bytes,
122
+ main: Annotated[bool | None, Field(default=None, description="Make this the document's primary file")] = None,
123
+ ) -> WriteResult:
124
+ """Attach a file to a document: its bytes, and the `filename` wflow should store it under.
125
+
126
+ The file joins whatever is already attached and nothing existing is touched. `main`
127
+ true instead makes it the document's primary file — the one
128
+ `download_document_main_file` fetches — which displaces the file holding that place
129
+ now; `list_document_files` says which one that is.
130
+
131
+ Fields: on the result —
132
+
133
+ - `action` — "created"
134
+ - `resource` — "documents/files"
135
+ - `id` — the new file's id, which `stamp_document_file`, `download_document_file` and
136
+ `delete_document_file` all take; null if wflow sends no body
137
+ """
138
+ created = await client.upload(
139
+ "PUT",
140
+ f"/api/{organization}/documents/{path_segment(documentId)}/files/upload",
141
+ filename,
142
+ content,
143
+ params=query_params(main=main),
144
+ )
145
+ return WriteResult(action="created", resource="documents/files", id=created)