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,603 @@
1
+ """Documents tag: the documents themselves, and everything hanging off one."""
2
+
3
+ import json
4
+ from typing import Annotated, Any
5
+
6
+ from pydantic import Field
7
+
8
+ from wflow_api.client import WflowClient
9
+ from wflow_api.guards import ensure_list, path_segment, query_params, write_json, write_json_list
10
+ from wflow_api.models import (
11
+ DocumentUpdate,
12
+ OrgSlug,
13
+ Page,
14
+ Paged,
15
+ PageSize,
16
+ PaymentCreate,
17
+ Query,
18
+ Search,
19
+ Sort,
20
+ StructuredFilter,
21
+ TeamBase,
22
+ WriteResult,
23
+ )
24
+ from wflow_api.models.common import FileContent
25
+ from wflow_api.models.documents import (
26
+ Comment,
27
+ Document,
28
+ DocumentBase,
29
+ DocumentEvent,
30
+ DocumentType,
31
+ DocumentTypeFull,
32
+ )
33
+ from wflow_api.operation import operation
34
+
35
+
36
+ @operation
37
+ async def list_documents(
38
+ client: WflowClient,
39
+ organization: OrgSlug,
40
+ sort: Sort = None,
41
+ query: Query = None,
42
+ pageSize: PageSize = None,
43
+ page: Page = None,
44
+ ) -> Paged[DocumentBase]:
45
+ """Documents in the workspace — invoices, contracts, orders and cash slips.
46
+
47
+ The starting point for any question about what a workspace contains. Use `query` to
48
+ narrow by amount, partner, date or status; use `get_document` for the full record
49
+ once you have an id. Note there is no `search` argument on this endpoint.
50
+
51
+ Fields:
52
+
53
+ - `number`, `serie`, `internalCode`, `variableSymbol` — how the document is identified
54
+ - `issueDate`, `dueDate`, `vatDate`, `acceptDate` — the dates that drive approval
55
+ and payment deadlines
56
+ - `totalAmount`, `taxExclusiveAmount`, `currency`, `exchangeRate` — the money
57
+ - `partnerName`, `partnerIC`, `partnerVAT` — who it is with
58
+ - `approvalStatus`, `flowStatus`, `locked`, `removed` — where it is in its lifecycle
59
+ - `type`, `tags`, `createdBy`, `created`, `updated`
60
+ """
61
+ payload = await client.request(
62
+ "GET",
63
+ f"/api/{organization}/documents",
64
+ params=query_params(sort=sort, query=query, pageSize=pageSize, page=page),
65
+ )
66
+ return Paged[DocumentBase].model_validate(payload or {})
67
+
68
+
69
+ @operation
70
+ async def get_document(client: WflowClient, organization: OrgSlug, documentId: str) -> Document:
71
+ """One document in full, including its lines, VAT breakdown and accounting.
72
+
73
+ `list_documents` returns a summary; this adds the lines and the resolved register
74
+ records a summary only names.
75
+
76
+ Fields: beyond those on the list summary —
77
+
78
+ - `lines` — the document lines, each with description, quantity, unit price, VAT
79
+ and its own accounting dimensions
80
+ - `vaTs` — the VAT breakdown per rate
81
+ - `accounting` — how the document is posted
82
+ - `partner`, `deliveryLocation` — the resolved register records; the list summary
83
+ carries only the names copied onto the document
84
+
85
+ Already on the list summary, not new here: `serie` (also a resolved record, not a
86
+ string), `payment`, `series` (a deprecated code, distinct from `serie`), `source`
87
+ and `dataSource`.
88
+ """
89
+ return Document.model_validate(
90
+ await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}") or {}
91
+ )
92
+
93
+
94
+ @operation
95
+ async def get_document_metadata(client: WflowClient, organization: OrgSlug, documentId: str) -> dict[str, Any]:
96
+ """Raw extraction metadata for a document — what wflow read off the source file.
97
+
98
+ Returned untyped on purpose: the spec describes the response only as "Metadata as
99
+ JSON string" and publishes no schema for it, so the shape is whatever wflow sends —
100
+ including, per that description, a JSON-encoded string rather than an object, which
101
+ this operation decodes for you. Treat the keys as unstable.
102
+
103
+ Fields: undocumented upstream. Inspect what comes back rather than assuming.
104
+ """
105
+ payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/metadata") or {}
106
+ # The spec calls this "Metadata as JSON string", so it may arrive double-encoded.
107
+ if isinstance(payload, str):
108
+ try:
109
+ payload = json.loads(payload)
110
+ except ValueError:
111
+ return {"metadata": payload}
112
+ return payload if isinstance(payload, dict) else {"metadata": payload}
113
+
114
+
115
+ @operation
116
+ async def list_document_events(client: WflowClient, organization: OrgSlug, documentId: str) -> list[DocumentEvent]:
117
+ """The audit trail of one document — every change, approval and file event, in order.
118
+
119
+ Read this to reconstruct what happened to a document and who did it, rather than
120
+ just its current state.
121
+
122
+ Fields:
123
+
124
+ - `type` — e.g. Create, Update, Approved, Rejected, FileAdded, ChangedFlowStatus
125
+ - `identity` — who triggered the event, when known
126
+ - `info` — free-text detail
127
+ - `created` — when it happened
128
+ """
129
+ payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/events") or []
130
+ return [DocumentEvent.model_validate(item) for item in payload]
131
+
132
+
133
+ @operation
134
+ async def list_documents_to_export(
135
+ client: WflowClient, organization: OrgSlug, typeId: str | None = None, exclude: bool | None = None
136
+ ) -> list[str]:
137
+ """Ids of documents ready to export to an ERP or accounting system.
138
+
139
+ Fields: a bare array of document ids, in no typed shape to model.
140
+
141
+ - `typeId` — restrict to one document type
142
+ - `exclude` — when true, ignore the document type's own "exclude from standard
143
+ integration into ERP" setting and return everything otherwise ready
144
+ """
145
+ path = f"/api/{organization}/documents/toexport"
146
+ payload = await client.request("GET", path, params=query_params(typeId=typeId, exclude=exclude)) or []
147
+ return ensure_list(path, payload)
148
+
149
+
150
+ @operation
151
+ async def list_documents_to_extract(client: WflowClient, organization: OrgSlug) -> list[str]:
152
+ """Ids of documents queued for data extraction from their source file.
153
+
154
+ Fields: a bare array of document ids, in no typed shape to model.
155
+ """
156
+ path = f"/api/{organization}/documents/toextract"
157
+ payload = await client.request("GET", path) or []
158
+ return ensure_list(path, payload)
159
+
160
+
161
+ @operation
162
+ async def list_document_comments(client: WflowClient, organization: OrgSlug, documentId: str) -> list[Comment]:
163
+ """The comment thread on one document.
164
+
165
+ Fields:
166
+
167
+ - `author` — who wrote it
168
+ - `text`, `markdown` — the comment content, plain and formatted
169
+ - `created`, `updated`, `removed`
170
+ - `teams` — which teams the comment is visible to, and whether each has resolved it
171
+ """
172
+ payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/comments") or []
173
+ return [Comment.model_validate(item) for item in payload]
174
+
175
+
176
+ @operation
177
+ async def list_document_links(client: WflowClient, organization: OrgSlug, documentId: str) -> list[DocumentBase]:
178
+ """Other documents linked to this one, e.g. an order linked to the invoice it produced.
179
+
180
+ Each item is a full document summary, the same shape `list_documents` returns, not
181
+ just an id — use it directly rather than following up with `get_document`. `created`
182
+ and `updated` are null on these summaries; `get_document` has them.
183
+
184
+ Fields: see `list_documents`.
185
+ """
186
+ payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/links") or []
187
+ return [DocumentBase.model_validate(item) for item in payload]
188
+
189
+
190
+ @operation
191
+ async def get_document_rights(client: WflowClient, organization: OrgSlug, documentId: str) -> list[TeamBase]:
192
+ """The teams allowed to see and act on one document.
193
+
194
+ Fields:
195
+
196
+ - `name`, `description` — the team as shown in wflow
197
+ - `system` — true for a built-in team rather than one the organization created
198
+ """
199
+ payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/rights") or []
200
+ return [TeamBase.model_validate(item) for item in payload]
201
+
202
+
203
+ @operation
204
+ async def get_document_type(client: WflowClient, organization: OrgSlug, typeId: str) -> DocumentTypeFull:
205
+ """One document type in full, including who has access to it.
206
+
207
+ `list_document_types` returns the summary; this adds the per-user permissions.
208
+
209
+ Fields: beyond those on the list summary —
210
+
211
+ - `users` — each user granted access, and their permission: All, OnlyAssigned
212
+ or FullAccess
213
+ """
214
+ # The published path segment is literal, not a parameter; typeId is a query argument.
215
+ payload = await client.request(
216
+ "GET", f"/api/{organization}/documents/types/typeid:guid", params=query_params(typeId=typeId)
217
+ )
218
+ return DocumentTypeFull.model_validate(payload or {})
219
+
220
+
221
+ @operation
222
+ async def list_document_types(
223
+ client: WflowClient,
224
+ organization: OrgSlug,
225
+ search: Search = None,
226
+ sort: Sort = None,
227
+ query: Query = None,
228
+ pageSize: PageSize = None,
229
+ page: Page = None,
230
+ ) -> Paged[DocumentType]:
231
+ """Document types configured in the workspace — the kinds a document may be filed as.
232
+
233
+ Look here to learn which numbering series and sequence a type uses before assigning
234
+ it, or to resolve the `type` field seen on a document. For one type's full detail,
235
+ including who may use it, follow up with `get_document_type`.
236
+
237
+ Fields:
238
+
239
+ - `name`, `kind` — the type as shown in wflow, and the document kind it applies to
240
+ - `default` — used automatically when a document arrives with no type set
241
+ - `erpExclude` — excluded from standard integration into an ERP
242
+ - `docCreatingMethod` — Upload or Manually
243
+ - `autoStamp` — when wflow time-stamps a file of this type: None, New or Approved
244
+ - `serie`, `sequence` — the numbering series and counter this type draws on
245
+ - `invoiceType` — TaxInvoice, CreditNote, DebitNote, Proforma or TaxInvoicePayment
246
+ """
247
+ payload = (
248
+ await client.request(
249
+ "GET",
250
+ f"/api/{organization}/documents/types",
251
+ params=query_params(search=search, sort=sort, query=query, pageSize=pageSize, page=page),
252
+ )
253
+ or {}
254
+ )
255
+ return Paged[DocumentType].model_validate(payload)
256
+
257
+
258
+ @operation
259
+ async def delete_document(client: WflowClient, organization: OrgSlug, documentId: str) -> WriteResult:
260
+ """Delete one document, with everything attached to it.
261
+
262
+ Its files, comments, properties and approval history go with it, and wflow keeps no
263
+ version history to restore it from. Read `get_document` first if you are not certain
264
+ which document the id refers to.
265
+
266
+ Fields: on the result —
267
+
268
+ - `action` — "deleted"
269
+ - `resource` — "documents"
270
+ """
271
+ await client.request("DELETE", f"/api/{organization}/documents/{path_segment(documentId)}")
272
+ return WriteResult(action="deleted", resource="documents")
273
+
274
+
275
+ @operation
276
+ async def unlink_document(
277
+ client: WflowClient, organization: OrgSlug, documentId: str, linkedDocumentId: str
278
+ ) -> WriteResult:
279
+ """Remove the link between two documents, leaving both documents in place.
280
+
281
+ Only the association goes. `list_document_links` returns the documents currently
282
+ linked to `documentId`, each as a full summary, so take `linkedDocumentId` from its
283
+ `id`.
284
+
285
+ Fields: on the result —
286
+
287
+ - `action` — "deleted"
288
+ - `resource` — "documents/links"
289
+ """
290
+ await client.request(
291
+ "DELETE", f"/api/{organization}/documents/{path_segment(documentId)}/links/{path_segment(linkedDocumentId)}"
292
+ )
293
+ return WriteResult(action="deleted", resource="documents/links")
294
+
295
+
296
+ @operation
297
+ async def delete_document_type(client: WflowClient, organization: OrgSlug, typeId: str) -> WriteResult:
298
+ """Delete one of the workspace's document types.
299
+
300
+ A type is workspace configuration shared by every document filed as it, not a
301
+ property of one document, so this reaches further than the id suggests. Get the id
302
+ from `list_document_types`.
303
+
304
+ Fields: on the result —
305
+
306
+ - `action` — "deleted"
307
+ - `resource` — "documents/types"
308
+ """
309
+ # The published path segment is literal, not a parameter; typeId is a query argument.
310
+ await client.request(
311
+ "DELETE", f"/api/{organization}/documents/types/typeid:guid", params=query_params(typeId=typeId)
312
+ )
313
+ return WriteResult(action="deleted", resource="documents/types")
314
+
315
+
316
+ @operation
317
+ async def lock_document(client: WflowClient, organization: OrgSlug, documentId: str, value: bool) -> WriteResult:
318
+ """Lock or unlock a document, so it cannot be changed while someone works on it.
319
+
320
+ Pass `value` true to lock, false to release. A locked document rejects writes until
321
+ it is unlocked; `update_document` can override that with `ignoreLock`.
322
+ `list_documents` reports the current state as `locked`.
323
+
324
+ Fields: on the result —
325
+
326
+ - `action` — "locked" or "unlocked"
327
+ - `resource` — "documents/lock"
328
+ """
329
+ await client.request("PUT", f"/api/{organization}/documents/{path_segment(documentId)}/lock/{str(value).lower()}")
330
+ return WriteResult(action="locked" if value else "unlocked", resource="documents/lock")
331
+
332
+
333
+ @operation
334
+ async def link_document(
335
+ client: WflowClient, organization: OrgSlug, documentId: str, linkedDocumentId: str
336
+ ) -> WriteResult:
337
+ """Link one document to another, e.g. an order to the invoice it produced.
338
+
339
+ Only the association is created; both documents stay as they are.
340
+ `list_document_links` then returns the linked document among `documentId`'s links,
341
+ and `unlink_document` takes the link off again.
342
+
343
+ Fields: on the result —
344
+
345
+ - `action` — "linked"
346
+ - `resource` — "documents/links"
347
+ """
348
+ await client.request(
349
+ "PUT", f"/api/{organization}/documents/{path_segment(documentId)}/links/{path_segment(linkedDocumentId)}"
350
+ )
351
+ return WriteResult(action="linked", resource="documents/links")
352
+
353
+
354
+ @operation
355
+ async def create_document_task(client: WflowClient, organization: OrgSlug, documentId: str, type: str) -> WriteResult:
356
+ """Queue work on a document — extracting its data, or exporting it onward.
357
+
358
+ `type` is "Extract" or "Export"; another value is rejected outright. The task is
359
+ queued rather than run here — `list_documents_to_extract` and
360
+ `list_documents_to_export` list the documents waiting, and whatever performs the
361
+ work closes the task with `set_document_task_processed`. An Export task closed with
362
+ `success` true moves the document on in its workflow (e.g. from SentToReview to
363
+ SentToERP), which is permanent: nothing moves it back.
364
+
365
+ Fields: on the result —
366
+
367
+ - `action` — "created"
368
+ - `resource` — "documents/task"
369
+ """
370
+ await client.request("POST", f"/api/{organization}/documents/{path_segment(documentId)}/task/{path_segment(type)}")
371
+ return WriteResult(action="created", resource="documents/task")
372
+
373
+
374
+ @operation
375
+ async def set_document_task_processed(
376
+ client: WflowClient, organization: OrgSlug, documentId: str, taskType: str, success: bool
377
+ ) -> WriteResult:
378
+ """Record that a document task has been dealt with, and whether it worked.
379
+
380
+ This is the other half of `create_document_task`: `taskType` is "Extract" or
381
+ "Export", and `success` false records a failed attempt rather than leaving the
382
+ document queued. Send it from whatever performed the work. Closing an Export task
383
+ with `success` true moves the document on in its workflow (e.g. from SentToReview to
384
+ SentToERP), which is permanent: nothing moves it back.
385
+
386
+ Fields: on the result —
387
+
388
+ - `action` — "processed"
389
+ - `resource` — "documents/task"
390
+ """
391
+ await client.request(
392
+ "PUT",
393
+ f"/api/{organization}/documents/{path_segment(documentId)}/task/{path_segment(taskType)}/processed",
394
+ params=query_params(success=success),
395
+ )
396
+ return WriteResult(action="processed", resource="documents/task")
397
+
398
+
399
+ @operation
400
+ async def update_document(
401
+ client: WflowClient,
402
+ organization: OrgSlug,
403
+ document: DocumentUpdate,
404
+ externalId: Annotated[
405
+ str | None, Field(default=None, description="Match an existing document by your ERP's id")
406
+ ] = None,
407
+ ignoreLock: Annotated[bool | None, Field(default=None, description="Write even if the document is locked")] = None,
408
+ setAsFilled: Annotated[bool | None, Field(default=None, description="Mark the document as fully filled in")] = None,
409
+ ) -> WriteResult:
410
+ """Create a document, or replace an existing one's contents.
411
+
412
+ Matched by the `id` inside `document`, or by the `externalId` argument when
413
+ reconciling against an ERP. Send the full record: do not rely on a field you leave
414
+ out being kept, and `lines` and `vaTs` are whole lists regardless, so a line you omit
415
+ is gone. `get_document` returns the record in full — read it first when
416
+ changing a document that exists, and send back the fields this operation declares rather
417
+ than the whole read, which also carries the status, timestamps and resolved register
418
+ records that only a read has. `ignoreLock` overrides a lock set by `lock_document`.
419
+
420
+ Fields: on the result —
421
+
422
+ - `action` — "updated"
423
+ - `resource` — "documents"
424
+ - `id` — the document's id, which wflow returns for this endpoint
425
+ """
426
+ created = await client.request(
427
+ "PUT",
428
+ f"/api/{organization}/documents",
429
+ params=query_params(externalId=externalId, ignoreLock=ignoreLock, setAsFilled=setAsFilled),
430
+ json=write_json(document),
431
+ )
432
+ return WriteResult(action="updated", resource="documents", id=created)
433
+
434
+
435
+ @operation
436
+ async def update_document_metadata(
437
+ client: WflowClient, organization: OrgSlug, documentId: str, metadata: str
438
+ ) -> WriteResult:
439
+ """Replace the extraction metadata wflow holds for one document.
440
+
441
+ `metadata` is a string, not an object: it travels as a JSON string body, so pass JSON
442
+ already encoded and wflow stores the text you gave. It replaces the whole blob rather
443
+ than merging into it, and wflow keeps no version history, so read
444
+ `get_document_metadata` first if any of what is there matters.
445
+
446
+ Fields: on the result —
447
+
448
+ - `action` — "updated"
449
+ - `resource` — "documents/metadata"
450
+ """
451
+ await client.request("PUT", f"/api/{organization}/documents/{path_segment(documentId)}/metadata", json=metadata)
452
+ return WriteResult(action="updated", resource="documents/metadata")
453
+
454
+
455
+ @operation
456
+ async def update_document_payments(
457
+ client: WflowClient, organization: OrgSlug, documentId: str, payments: list[PaymentCreate]
458
+ ) -> WriteResult:
459
+ """Replace the payments recorded against one document.
460
+
461
+ The list you send becomes the document's payments, so a payment you leave out is
462
+ gone. wflow publishes no read for the individual payments — `get_document`'s
463
+ `payment` is a rollup of paid amount, date and status — so nothing can reconstruct
464
+ what a partial payload dropped. Send every payment you mean to keep.
465
+
466
+ Fields: on the result —
467
+
468
+ - `action` — "updated"
469
+ - `resource` — "documents/payments"
470
+ """
471
+ await client.request(
472
+ "PUT",
473
+ f"/api/{organization}/documents/{path_segment(documentId)}/payments",
474
+ json=write_json_list(payments),
475
+ )
476
+ return WriteResult(action="updated", resource="documents/payments")
477
+
478
+
479
+ @operation
480
+ async def update_document_type(
481
+ client: WflowClient, organization: OrgSlug, documentType: DocumentTypeFull
482
+ ) -> WriteResult:
483
+ """Create a document type, or replace an existing one's configuration.
484
+
485
+ A type is workspace configuration shared by every document filed as it, not a
486
+ property of one document. Matched by the `id` inside `documentType`; the submitted
487
+ object replaces the stored type, so a field you leave out can be cleared, and `users`
488
+ is a whole set — a user you omit loses access to the type and to every document filed
489
+ as it. That includes you: leave the caller (`id` from `get_me`) out of `users`
490
+ and `create_document_with_files` refuses to file anything as this type, because the
491
+ caller no longer has access to it. `get_document_type` returns it in full,
492
+ `users` included; read it first when changing a type that exists.
493
+
494
+ Fields: on the result —
495
+
496
+ - `action` — "updated"
497
+ - `resource` — "documents/types"
498
+ - `id` — the document type's id
499
+ """
500
+ created = await client.request(
501
+ "PUT",
502
+ f"/api/{organization}/documents/types",
503
+ json=write_json(documentType),
504
+ )
505
+ return WriteResult(action="updated", resource="documents/types", id=created)
506
+
507
+
508
+ @operation
509
+ async def set_document_rights(
510
+ client: WflowClient, organization: OrgSlug, documentId: str, teams: list[TeamBase]
511
+ ) -> WriteResult:
512
+ """Replace the set of teams allowed to see and act on one document.
513
+
514
+ The list you send becomes the document's rights, so a team you leave out loses
515
+ access, and an empty list leaves the document visible to nobody but full-access
516
+ users. `get_document_rights` returns every team currently allowed, in one array —
517
+ read it first and send its records straight back, minus the ones you are removing.
518
+ A team is matched by `id`, which `list_teams` also returns.
519
+
520
+ Fields: on the result —
521
+
522
+ - `action` — "updated"
523
+ - `resource` — "documents/rights"
524
+ """
525
+ await client.request(
526
+ "PUT",
527
+ f"/api/{organization}/documents/{path_segment(documentId)}/rights",
528
+ json=write_json_list(teams, allow_empty=True),
529
+ )
530
+ return WriteResult(action="updated", resource="documents/rights")
531
+
532
+
533
+ @operation
534
+ async def create_document_with_files(
535
+ client: WflowClient,
536
+ organization: OrgSlug,
537
+ filename: str,
538
+ content: bytes,
539
+ typeId: Annotated[str | None, Field(default=None, description="Document type to file it under")] = None,
540
+ invoiceType: Annotated[
541
+ str | None,
542
+ Field(default=None, description="TaxInvoice, CreditNote, DebitNote, Proforma or TaxInvoicePayment"),
543
+ ] = None,
544
+ ) -> WriteResult:
545
+ """Create a document from a file: its bytes, and the `filename` wflow should store it under.
546
+
547
+ This is how a scan becomes a document: wflow files it under `typeId`, which
548
+ `list_document_types` names, and reads what it can out of the file itself — an ISDOC,
549
+ or the QR receipt on a Slovak one — into the new document's fields. It sends one file
550
+ per call and hands back no document id, so to attach anything further, find the new
551
+ document with `list_documents` — `sort` of "created desc" puts it first — and pass its
552
+ id to `upload_document_file`. A refusal for lack of access to the document type means
553
+ the caller is not in that type's `users`, which `get_document_type` lists.
554
+
555
+ Fields: on the result —
556
+
557
+ - `action` — "created"
558
+ - `resource` — "documents/withfiles"
559
+ """
560
+ await client.upload(
561
+ "POST",
562
+ f"/api/{organization}/documents/withfiles",
563
+ filename,
564
+ content,
565
+ params=query_params(typeId=typeId, invoiceType=invoiceType),
566
+ field="uploadedFiles",
567
+ )
568
+ return WriteResult(action="created", resource="documents/withfiles")
569
+
570
+
571
+ @operation
572
+ async def export_documents(
573
+ client: WflowClient,
574
+ organization: OrgSlug,
575
+ format: str,
576
+ filter: StructuredFilter,
577
+ *,
578
+ max_bytes: int | None = None,
579
+ ) -> FileContent:
580
+ """Export a set of documents as one file, in an accounting system's own format.
581
+
582
+ `format` is one of "byznyssolitea", "datev", "excel", "generic", "isdoc", "kros",
583
+ "moneyerp", "moneys3", "mrp", "premier" or "xml"; another value is rejected outright.
584
+ `filter` chooses which documents go in — `filters` per column, `propertyFilters` per
585
+ custom property, `search` as free text — and **`sort` is required**: pass something
586
+ like "number asc", because wflow fails the export without it, an empty `filter`
587
+ object included. The other three are optional and default to no restriction.
588
+
589
+ wflow streams the export file itself, whatever the format, and it comes back as its own
590
+ bytes. With `max_bytes` set, a larger export is refused rather than truncated.
591
+
592
+ Fields:
593
+
594
+ - `filename` — whatever wflow's Content-Disposition names, when it sends one
595
+ - `content_type` — the MIME type wflow gave the export
596
+ - `content` — the export's bytes
597
+ """
598
+ return await client.download(
599
+ f"/api/{organization}/documents/export/{path_segment(format)}",
600
+ "POST",
601
+ json=write_json(filter.with_empty_restrictions()),
602
+ max_bytes=max_bytes,
603
+ )
@@ -0,0 +1,63 @@
1
+ """Integrations tag: minting an API client, and what one is allowed to do in a workspace."""
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 query_params
9
+ from wflow_api.models import ApiClientResult, OrgSlug, WriteResult
10
+ from wflow_api.operation import operation
11
+
12
+
13
+ @operation
14
+ async def allow_integration(client: WflowClient, organization: OrgSlug) -> WriteResult:
15
+ """Allow the calling client to integrate with this workspace.
16
+
17
+ wflow applies it to the client the request is authenticated as: there is nothing to
18
+ name, and it cannot grant access to a different one. `organization` is the only
19
+ choice being made here, so check it is the workspace you mean.
20
+
21
+ Fields: on the result —
22
+
23
+ - `action` — "allowed"
24
+ - `resource` — "integrations/allow"
25
+ """
26
+ await client.request("PUT", f"/api/{organization}/integrations/allow")
27
+ return WriteResult(action="allowed", resource="integrations/allow")
28
+
29
+
30
+ @operation
31
+ async def create_api_client(
32
+ client: WflowClient,
33
+ organization: OrgSlug,
34
+ name: str,
35
+ sufix: Annotated[
36
+ str | None, Field(default=None, description="Suffix appended to the generated client name")
37
+ ] = None,
38
+ alwaysAllow: Annotated[
39
+ bool | None,
40
+ Field(default=None, description="Create it already allowed, so it needs no allow_integration call"),
41
+ ] = None,
42
+ ) -> ApiClientResult:
43
+ """Mint a machine-to-machine API client for this workspace.
44
+
45
+ **The result contains a client secret, shown once and never again.** Hand it to the
46
+ person who asked for it and do not repeat it in a summary, a commit message or a
47
+ file. If it is lost, the client has to be created again.
48
+
49
+ This is a `client_credentials` pair for a customer's own integration. It is not an
50
+ `authorization_code` client for an interactive application — those have to be
51
+ requested from the wflow identity administrators.
52
+
53
+ Fields: on the result —
54
+
55
+ - `id` — the generated client id
56
+ - `secret` — the client secret, shown only here
57
+ """
58
+ payload = await client.request(
59
+ "POST",
60
+ f"/api/{organization}/integrations/apiclient",
61
+ params=query_params(name=name, sufix=sufix, alwaysAllow=alwaysAllow),
62
+ )
63
+ return ApiClientResult.model_validate(payload or {})