@deliverd/sdk 0.10.0 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/types.ts CHANGED
@@ -1,933 +1,1107 @@
1
- /**
2
- * The API's objects, by hand.
3
- *
4
- * Not imported from the server's zod schemas on purpose: this package is
5
- * published to npm and must not drag the monorepo's internals with it. The
6
- * cost of that is drift, so `apps/web/src/lib/services/api-approvals.test.ts`
7
- * holds these shapes to the schemas the API actually validates — a field added
8
- * there and not here fails the build on the server side, where someone is
9
- * looking.
10
- */
11
-
12
- export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled";
13
- export type ApprovalRisk = "low" | "medium" | "high" | "critical";
14
-
15
- /**
16
- * What a gate decision can be.
17
- *
18
- * Seven, and the extra four over `allowed | denied | pending` are worth the
19
- * width. `allowed` and `denied` are what a *rule* said; the rest are what a
20
- * *person* did about a request no rule settled. An action that went through
21
- * because policy permitted it and one that went through because somebody
22
- * agreed to it are not the same fact — the ratio between them is the number
23
- * this whole layer exists to make computable — so collapsing them would throw
24
- * away the distinction at the one place a caller can see it.
25
- */
26
- export type GateStatus =
27
- | "allowed"
28
- | "denied"
29
- | "pending"
30
- | "approved"
31
- | "rejected"
32
- | "expired"
33
- | "cancelled";
34
-
35
- /** What a person decided about a gate, once one has. */
36
- export type GateOutcomeName = "approved" | "rejected" | "cancelled" | "expired";
37
-
38
- export interface CreateGateInput {
39
- /** The registered action you are about to perform: `finance.refund`. */
40
- actionId: string;
41
- /** The arguments you will actually execute with. Validated against the action's schema. */
42
- input: Record<string, unknown>;
43
- /**
44
- * Your id for this unit of work — `refund:ord_8812`. **Required**, which no
45
- * other create in this SDK is.
46
- *
47
- * Every other POST mints a random idempotency key per attempt, which guards a
48
- * retried *request*. This guards a retried *decision*: a crashed agent that
49
- * re-runs its refund step must re-read the answer it already got, not ask a
50
- * second person about the same money. No id the SDK invented could know which
51
- * two calls are the same attempt, so you name it.
52
- */
53
- externalId: string;
54
- /** Where this is running, for rules that tell staging from production. */
55
- environment?: string;
56
- /** Why, shown to whoever is asked to decide. */
57
- reason?: string;
58
- flowId?: string;
59
- }
60
-
61
- export interface GateData {
62
- id: string;
63
- status: GateStatus;
64
- /** The one to branch on: a rule permitted it, or a person agreed to it. */
65
- allowed: boolean;
66
- /**
67
- * What to execute with: the input as the action's schema validated it, or
68
- * the approver's correction of it when they approved with changes.
69
- */
70
- input: Record<string, unknown>;
71
- /** What the approver changed in it. Empty unless they did. */
72
- changes: FieldChange[];
73
- /**
74
- * What the organisation's ethics rules asked whoever decides to weigh, as
75
- * they read when this was asked. Empty when nothing matched. A flagged
76
- * request is approved with a written reason, never from a sign-in-free link.
77
- */
78
- concerns: { principle: string; rule: string; concern: string }[];
79
- /** Whether a rule decided this or a person did. */
80
- basis: "policy" | "human";
81
- reason: string | null;
82
- /** The rule that decided, by name. Null when nothing matched. */
83
- rule: string | null;
84
- policyVersionId: string | null;
85
- approvalId: string | null;
86
- approvalUrl: string | null;
87
- outcome: GateOutcomeName | null;
88
- settledAt: string | null;
89
- /** True when this call found a decision already made under your `externalId`. */
90
- reused: boolean;
91
- }
92
-
93
- /**
94
- * The answer, flattened — what `gate()` hands back.
95
- *
96
- * `allowed` is a boolean so `if (decision.allowed)` reads as the sentence it
97
- * is; `status` is the narrowing union for a switch. The same pairing, for the
98
- * same reason, as `Decision` on an approval.
99
- */
100
- export interface GateDecision {
101
- allowed: boolean;
102
- status: GateStatus;
103
- reason: string | null;
104
- rule: string | null;
105
- /** What to execute with, corrections included. */
106
- input: Record<string, unknown>;
107
- /** What the approver changed. Empty unless they did. */
108
- changes: FieldChange[];
109
- id: string;
110
- approvalUrl: string | null;
111
- gate: unknown;
112
- }
113
-
114
- /** One field an approver corrected before approving. */
115
- export interface FieldChange {
116
- field: string;
117
- from: unknown;
118
- to: unknown;
119
- }
120
-
121
- /** One line of evidence, as the approval page shows it. */
122
- export interface ApprovalFactor {
123
- label: string;
124
- status?: "ok" | "warning" | "info";
125
- detail?: string;
126
- }
127
-
128
- export interface ApprovalLink {
129
- label: string;
130
- url: string;
131
- }
132
-
133
- export interface ApprovalQuestion {
134
- id: string;
135
- question: string;
136
- answer: string | null;
137
- askedAt: string;
138
- answeredAt: string | null;
139
- }
140
-
141
- export interface ApprovalData {
142
- id: string;
143
- status: ApprovalStatus;
144
- /** The page the approver decides on. */
145
- url: string;
146
- title: string;
147
- description: string | null;
148
- risk: ApprovalRisk;
149
- factors: ApprovalFactor[];
150
- links: ApprovalLink[];
151
- reportId: string | null;
152
- externalId: string | null;
153
- metadata: Record<string, unknown>;
154
- /** What you proposed to run with, unchanged. */
155
- input: Record<string, unknown> | null;
156
- /** Which fields of it the approver may correct. */
157
- editableFields: string[];
158
- /** What to run with once approved: `input` with any corrections. Null until then. */
159
- approvedInput: Record<string, unknown> | null;
160
- /** What the approver changed. */
161
- changes: FieldChange[];
162
- /**
163
- * What the organisation's ethics rules asked whoever decides to weigh, as
164
- * they read when this was asked. Empty when nothing matched. A flagged
165
- * request is approved with a written reason, never from a sign-in-free link.
166
- */
167
- concerns: { principle: string; rule: string; concern: string }[];
168
- requestedBy: string;
169
- approvers: string[];
170
- /**
171
- * How many people must agree before it settles. One unless a standing rule
172
- * in the organisation escalated it — an agent cannot set this, and a rule
173
- * can only push it up.
174
- */
175
- requiredApprovals: number;
176
- /** How many have approved so far. Compare with `requiredApprovals`. */
177
- approvalsSoFar: number;
178
- /** Who decided, as a name rather than an id — the same as a review's `by`. */
179
- decidedBy: string | null;
180
- /** Their user id, for anything that needs the key rather than the person. */
181
- decidedById: string | null;
182
- decidedAt: string | null;
183
- /** The approver's reason, on a rejection or an approval that carried one. */
184
- note: string | null;
185
- expiresAt: string | null;
186
- questions: ApprovalQuestion[];
187
- createdAt: string;
188
- }
189
-
190
- export interface CreateApprovalInput {
191
- /** What is being asked, as a headline. */
192
- title: string;
193
- /** Why, what it affects, what it costs — what the approver reads first. */
194
- description?: string;
195
- /** How the approver should weigh it. Medium when omitted. */
196
- risk?: ApprovalRisk;
197
- /** Evidence, one line each, shown as a checklist. */
198
- factors?: ApprovalFactor[];
199
- /** Where to read more. */
200
- links?: ApprovalLink[];
201
- /** A published report the request is about. */
202
- reportId?: string;
203
- /**
204
- * Who may decide. Each entry is a person — an email or a user id — or the
205
- * name of a directory group or workspace, or a word meaning the whole
206
- * organisation ("everyone"). Naming a team is usually what you want: a
207
- * request addressed to one person waits for that person to come back from
208
- * holiday, and anyone on a team can answer.
209
- *
210
- * The organisation's owners and admins decide when this is omitted. You
211
- * cannot name only yourself; being *on* a team you address is fine and means
212
- * the rest of it. A name matching both a person and a team is refused rather
213
- * than guessed — name it by id.
214
- */
215
- approvers?: string[];
216
- /** After this the request expires undecided. ISO 8601. */
217
- expiresAt?: string;
218
- /** Your own reference, returned unchanged and searchable. */
219
- externalId?: string;
220
- /**
221
- * The flow this belongs to, when it is one step of a larger piece of work.
222
- * Must be an open flow in your organisation. `flow.approve()` and its
223
- * siblings set this for you.
224
- */
225
- flowId?: string;
226
- /**
227
- * Where to POST the outcome when a person answers, instead of polling:
228
- * HTTPS, and a public address. The call that makes the request returns the
229
- * secret its callbacks are signed with (`callbackSecret` on the handle).
230
- */
231
- callbackUrl?: string;
232
- metadata?: Record<string, unknown>;
233
- /**
234
- * The arguments you will run with if this is approved, shown to the
235
- * approver. The decision's `input` is what to actually run with.
236
- */
237
- input?: Record<string, unknown>;
238
- /**
239
- * Fields of `input` the approver may correct before approving: strings,
240
- * numbers and true/false. Omitted, it is approve or reject only.
241
- */
242
- editableFields?: string[];
243
- }
244
-
245
- /**
246
- * The answer to `approve()`.
247
- *
248
- * Flat on purpose: the line after the call is `if (decision.approved)`, and
249
- * anything a caller has to reach through to get there is a step this SDK
250
- * exists to remove. The whole request is on `approval` when a field here does
251
- * not cover it.
252
- */
253
- export type Decision = {
254
- /** True only for an approval. False for rejected, expired and cancelled. */
255
- approved: boolean;
256
- /** For a switch, and for narrowing. */
257
- status: "approved" | "rejected" | "expired" | "cancelled";
258
- /** Their reason, when they gave one. */
259
- note: string | null;
260
- /** Who decided, as a name rather than an id. Log it; put it in a message. */
261
- decidedBy: string | null;
262
- /** Their user id, when the key is what you need. */
263
- decidedById: string | null;
264
- decidedAt: string | null;
265
- id: string;
266
- /** The page they decided on. Worth logging. */
267
- url: string;
268
- /**
269
- * What to run with, when you sent an `input` and it was approved: yours,
270
- * with any corrections the approver made. Null otherwise — never run the
271
- * proposal when this is null.
272
- */
273
- input: Record<string, unknown> | null;
274
- /** What the approver changed. Empty when they approved it as proposed. */
275
- changes: FieldChange[];
276
- /** The request itself, for anything the fields above do not name. */
277
- approval: unknown;
278
- };
279
-
280
- export interface ListApprovalsInput {
281
- status?: ApprovalStatus;
282
- externalId?: string;
283
- /** One page of this size. Leave it unset to get every row. */
284
- limit?: number;
285
- /** `nextCursor` from a previous page. Only meaningful with `limit`. */
286
- cursor?: string;
287
- }
288
-
289
- /* ── Reports ─────────────────────────────────────────────────────────────── */
290
-
291
- export interface InlineFile {
292
- path: string;
293
- content: string;
294
- /** `base64` for an image or a font; text otherwise. */
295
- encoding?: "utf8" | "base64";
296
- }
297
-
298
- export interface PublishReportInput {
299
- title?: string;
300
- slug?: string;
301
- description?: string;
302
- workspaceId?: string;
303
- /** Names, teams, groups or emails — resolved server-side. */
304
- audience?: unknown;
305
- classification?: string;
306
- living?: boolean;
307
- sourceTool?: string;
308
- sourceModel?: string;
309
- changeSummary?: string;
310
- /** Publish only if this is still the current version; 0 claims a new slug. */
311
- expectedVersion?: number;
312
- uploadId?: string;
313
- content?: string;
314
- files?: InlineFile[];
315
- }
316
-
317
- export type UpdateReportInput = Pick<
318
- PublishReportInput,
319
- | "uploadId"
320
- | "content"
321
- | "files"
322
- | "title"
323
- | "description"
324
- | "sourceTool"
325
- | "sourceModel"
326
- | "changeSummary"
327
- | "expectedVersion"
328
- >;
329
-
330
- export interface ReportData {
331
- id: string;
332
- slug: string;
333
- title: string;
334
- url: string;
335
- status: string;
336
- currentVersion: number | null;
337
- [key: string]: unknown;
338
- }
339
-
340
- /**
341
- * A publish held by a policy rule answers 202 with this instead of going live.
342
- * `status` says which happened, so a caller that ignores it still gets a
343
- * report object and a caller that reads it knows nobody can see the thing yet.
344
- */
345
- export interface PublishResult {
346
- status?: "published" | "updated" | "pending_approval";
347
- report: ReportData;
348
- version?: { id: string; versionNumber: number; [key: string]: unknown };
349
- approval?: { id: string; status: string };
350
- warnings?: string[];
351
- [key: string]: unknown;
352
- }
353
-
354
- /**
355
- * One open thread, as the organisation-wide list returns it.
356
- *
357
- * Deliberately thinner than a `CommentThread`: this answers "where is the
358
- * feedback" across every report, so it carries the report and the quoted
359
- * passage rather than the whole conversation. Fetch the thread itself with
360
- * `comments.list(reportId)` once you know which report to look at.
361
- */
362
- export interface OpenThread {
363
- threadId: string;
364
- reportId: string;
365
- reportTitle: string;
366
- reportSlug: string;
367
- /** Who owns the report — filter on it to find the threads on yours. */
368
- reportOwnerId: string | null;
369
- quote: string | null;
370
- author: string;
371
- authorType: string;
372
- messages: number;
373
- lastActivityAt: string;
374
- }
375
-
376
- /**
377
- * What a send did, per address.
378
- *
379
- * `delivered` is the mail provider accepting it, not the person reading it —
380
- * and `alreadyHadAccess` names the recipients who could already open the
381
- * report, who were emailed again anyway. Re-sending to somebody who says
382
- * they never got the first one is the point.
383
- */
384
- export interface SendResult {
385
- sent: { email: string; delivered: boolean }[];
386
- alreadyHadAccess: string[];
387
- }
388
-
389
- /* ── Schedules ───────────────────────────────────────────────────────────── */
390
-
391
- /**
392
- * A recurring publish an agent is expected to perform.
393
- *
394
- * `due` is the useful field: true once the schedule has fired and nobody has
395
- * acted on that firing. Publishing a new version clears it, and so does
396
- * writing a dataset — for a report that reads its numbers from `_data/…`,
397
- * updating the data is the whole job.
398
- */
399
- export interface ScheduleSummary {
400
- id: string;
401
- reportId: string;
402
- reportSlug: string;
403
- reportTitle: string;
404
- reportUrl: string;
405
- agentId: string;
406
- agentName: string;
407
- /** Five-field cron expression, evaluated in UTC. */
408
- recurrence: string;
409
- enabled: boolean;
410
- lastRunAt: string | null;
411
- nextRunAt: string | null;
412
- currentVersion: number | null;
413
- due: boolean;
414
- dueSince: string | null;
415
- }
416
-
417
- /* ── Comments ────────────────────────────────────────────────────────────── */
418
-
419
- export interface CommentThread {
420
- threadId: string;
421
- status: "open" | "resolved";
422
- quote: string | null;
423
- messages: {
424
- /** What `comments.retract` takes. */
425
- commentId: string;
426
- author: string;
427
- authorType: string;
428
- body: string;
429
- createdAt: string;
430
- /** True for the one message this credential could still take back. */
431
- retractable: boolean;
432
- }[];
433
- [key: string]: unknown;
434
- }
435
-
436
- /* ── Analytics ───────────────────────────────────────────────────────────── */
437
-
438
- /** Who read one report. The detail beyond `totalViews` needs the analytics plan. */
439
- export interface ReportAnalytics {
440
- reportId: string;
441
- title: string;
442
- totalViews: number;
443
- uniqueViewers: number | null;
444
- internalViewers: number | null;
445
- externalViewers: number | null;
446
- firstViewedAt: string | null;
447
- lastViewedAt: string | null;
448
- byDay: { day: string; views: number; uniqueViewers: number }[];
449
- byVersion: {
450
- versionNumber: number;
451
- views: number;
452
- uniqueViewers: number;
453
- lastViewedAt: string | null;
454
- }[];
455
- /** Names only where the organisation shows viewer identities. */
456
- recentViewers: {
457
- displayName: string;
458
- principalType: string;
459
- viewCount: number;
460
- lastViewedAt: string;
461
- }[];
462
- }
463
-
464
- /** What is being read across every report, and what is not being read at all. */
465
- export interface OrgAnalytics {
466
- days: number;
467
- totalViews: number;
468
- uniqueViewers: number;
469
- activeReports: number;
470
- externallySharedReports: number;
471
- publicReports: number;
472
- publishesInPeriod: number;
473
- topReports: {
474
- reportId: string;
475
- title: string;
476
- views: number;
477
- uniqueViewers: number;
478
- lastViewedAt: string | null;
479
- }[];
480
- /** Live reports with no view in the period — oldest silence first. */
481
- inactiveReports: {
482
- reportId: string;
483
- title: string;
484
- lastViewedAt: string | null;
485
- publishedAt: string | null;
486
- }[];
487
- }
488
-
489
- /* ── Webhooks ────────────────────────────────────────────────────────────── */
490
-
491
- export type WebhookEventName =
492
- | "report.published"
493
- | "report.updated"
494
- | "report.shared"
495
- | "report.viewed"
496
- | "comment.created"
497
- | "access.requested"
498
- | "schedule.due"
499
- | "publish.held"
500
- | "approval.requested"
501
- | "approval.approved"
502
- | "approval.rejected"
503
- | "approval.expired"
504
- | "approval.escalated"
505
- | "approval.question"
506
- | "approval.answered"
507
- | "review.requested"
508
- | "review.approved"
509
- | "review.changes_requested"
510
- | "collection.requested"
511
- | "collection.completed"
512
- | "flow.completed"
513
- /** A gate refused. The only gate event that relays: an allow fires on every
514
- * auto-allowed action, and an escalation already arrives as
515
- * `approval.requested`. */
516
- | "gate.denied";
517
-
518
- export interface WebhookEvent {
519
- event: WebhookEventName;
520
- sentAt: string;
521
- /** Present and true when sent by the Send test button, not by real activity. */
522
- test?: boolean;
523
- data: Record<string, unknown>;
524
- }
525
-
526
- /* ── Reviews ──────────────────────────────────────────────────────────────── */
527
-
528
- export type ReviewStatus =
529
- | "pending"
530
- | "approved"
531
- | "changes_requested"
532
- | "expired"
533
- | "cancelled";
534
-
535
- export interface CreateReviewInput {
536
- /** What is being reviewed, as a headline the reviewer sees first. */
537
- title: string;
538
- /**
539
- * What to check. Without this a reviewer decides what "review" means, and
540
- * usually decides it means "looks fine".
541
- */
542
- instructions?: string;
543
- /** The published report under review; the reviewer reads it and comments on it. */
544
- reportId?: string;
545
- /** Pin a version, so publishing again mid-review does not move the ground. */
546
- versionId?: string;
547
- /**
548
- * Emails or user ids. An active member, or a guest who can already open the
549
- * report — anyone else is refused rather than emailed. You cannot name
550
- * yourself.
551
- */
552
- reviewers: string[];
553
- /**
554
- * How many approvals settle it; one when omitted. A single "changes
555
- * requested" settles it regardless.
556
- */
557
- requiredApprovals?: number;
558
- /** After this the review expires unanswered. ISO 8601. */
559
- expiresAt?: string;
560
- /** Your own reference, returned unchanged and searchable. */
561
- externalId?: string;
562
- /**
563
- * The flow this belongs to, when it is one step of a larger piece of work.
564
- * Must be an open flow in your organisation. `flow.approve()` and its
565
- * siblings set this for you.
566
- */
567
- flowId?: string;
568
- /**
569
- * Where to POST the outcome when a person answers, instead of polling:
570
- * HTTPS, and a public address. The call that makes the request returns the
571
- * secret its callbacks are signed with (`callbackSecret` on the handle).
572
- */
573
- callbackUrl?: string;
574
- metadata?: Record<string, unknown>;
575
- }
576
-
577
- export interface ReviewerRef {
578
- kind: "user" | "guest";
579
- id: string;
580
- label: string;
581
- }
582
-
583
- export interface ReviewVerdict {
584
- verdict: "approved" | "changes_requested";
585
- /** Who gave it, as a name rather than an id. */
586
- by: string;
587
- note: string | null;
588
- at: string;
589
- }
590
-
591
- export interface ReviewData {
592
- id: string;
593
- status: ReviewStatus;
594
- /** The page the reviewer reads and decides on. */
595
- url: string;
596
- title: string;
597
- instructions: string | null;
598
- reportId: string | null;
599
- versionId: string | null;
600
- externalId: string | null;
601
- metadata: Record<string, unknown>;
602
- requestedBy: string;
603
- requiredApprovals: number;
604
- reviewers: ReviewerRef[];
605
- verdicts: ReviewVerdict[];
606
- /** How many comment threads the reviewers opened while reading. */
607
- threadCount: number;
608
- settledAt: string | null;
609
- expiresAt: string | null;
610
- createdAt: string;
611
- }
612
-
613
- /** The answer, flattened — what `review()` hands back. */
614
- export interface ReviewOutcome {
615
- /** The one to branch on. False for changes requested, expired and cancelled. */
616
- approved: boolean;
617
- status: Exclude<ReviewStatus, "pending">;
618
- /** Every verdict returned, in the order they arrived. */
619
- verdicts: ReviewVerdict[];
620
- /** How many comment threads to read before producing the next version. */
621
- threadCount: number;
622
- id: string;
623
- url: string;
624
- review: ReviewData;
625
- }
626
-
627
- export interface ListReviewsInput {
628
- status?: ReviewStatus;
629
- externalId?: string;
630
- reportId?: string;
631
- /** One page of this size. Leave it unset to get every row. */
632
- limit?: number;
633
- /** `nextCursor` from a previous page. Only meaningful with `limit`. */
634
- cursor?: string;
635
- }
636
-
637
- /* ── Collections ──────────────────────────────────────────────────────────── */
638
-
639
- export type CollectionStatus = "pending" | "complete" | "expired" | "cancelled";
640
-
641
- export type QuestionKind =
642
- | "text"
643
- | "long_text"
644
- | "number"
645
- | "date"
646
- | "choice"
647
- | "multi_choice"
648
- | "boolean";
649
-
650
- /** What an answer can hold, shaped by its question's kind. */
651
- export type AnswerValue = string | number | boolean | string[];
652
-
653
- export interface QuestionInput {
654
- /** The question, as you would ask it out loud. */
655
- prompt: string;
656
- /** The sentence under the field that stops the wrong answer being given. */
657
- help?: string;
658
- kind: QuestionKind;
659
- /** Required unless you say otherwise; a required question blocks submission. */
660
- required?: boolean;
661
- /** For `choice` and `multi_choice`. At least two, or it is not a question. */
662
- options?: string[];
663
- }
664
-
665
- export interface CreateCollectionInput {
666
- /** What you need, as a headline the person sees first. */
667
- title: string;
668
- /** Why you are asking, shown above the questions. */
669
- instructions?: string;
670
- questions: QuestionInput[];
671
- /**
672
- * Emails or user ids. An active member, or a guest the organisation already
673
- * knows — anyone else is refused rather than emailed.
674
- */
675
- respondents: string[];
676
- /** How many submitted replies complete it; everyone asked, when omitted. */
677
- requiredResponses?: number;
678
- /** A published report the request is about. */
679
- reportId?: string;
680
- /** Shown to the person, and what the single reminder is measured against. */
681
- dueAt?: string;
682
- /** After this the request closes unanswered. ISO 8601. */
683
- expiresAt?: string;
684
- externalId?: string;
685
- /**
686
- * The flow this belongs to, when it is one step of a larger piece of work.
687
- * Must be an open flow in your organisation. `flow.approve()` and its
688
- * siblings set this for you.
689
- */
690
- flowId?: string;
691
- /**
692
- * Where to POST the outcome when a person answers, instead of polling:
693
- * HTTPS, and a public address. The call that makes the request returns the
694
- * secret its callbacks are signed with (`callbackSecret` on the handle).
695
- */
696
- callbackUrl?: string;
697
- metadata?: Record<string, unknown>;
698
- }
699
-
700
- export interface CollectionQuestion {
701
- id: string;
702
- prompt: string;
703
- help: string | null;
704
- kind: QuestionKind;
705
- required: boolean;
706
- options: string[];
707
- }
708
-
709
- export interface CollectionReply {
710
- /** Who answered, as a name rather than an id. */
711
- respondent: string;
712
- status: "pending" | "submitted";
713
- submittedAt: string | null;
714
- /** Empty until they submit: a half-typed draft is not what they meant to say. */
715
- answers: { question: string; kind: QuestionKind; value: AnswerValue }[];
716
- }
717
-
718
- export interface CollectionData {
719
- id: string;
720
- status: CollectionStatus;
721
- /** The page the person fills in. */
722
- url: string;
723
- title: string;
724
- instructions: string | null;
725
- reportId: string | null;
726
- externalId: string | null;
727
- metadata: Record<string, unknown>;
728
- requestedBy: string;
729
- requiredResponses: number;
730
- questions: CollectionQuestion[];
731
- responses: CollectionReply[];
732
- submittedCount: number;
733
- askedCount: number;
734
- settledAt: string | null;
735
- dueAt: string | null;
736
- expiresAt: string | null;
737
- createdAt: string;
738
- }
739
-
740
- /** The answers, flattened — what `collect()` hands back. */
741
- export interface CollectedAnswers {
742
- /** True when enough people replied; false if it expired or was withdrawn. */
743
- complete: boolean;
744
- status: Exclude<CollectionStatus, "pending">;
745
- /** Every submitted reply, in the order they arrived. */
746
- responses: CollectionReply[];
747
- /**
748
- * The first submitted answer to each question, by its prompt — the shape
749
- * most callers want when they asked one person for three facts.
750
- */
751
- answers: Record<string, AnswerValue>;
752
- id: string;
753
- url: string;
754
- collection: CollectionData;
755
- }
756
-
757
- export interface ListCollectionsInput {
758
- status?: CollectionStatus;
759
- externalId?: string;
760
- /** One page of this size. Leave it unset to get every row. */
761
- limit?: number;
762
- /** `nextCursor` from a previous page. Only meaningful with `limit`. */
763
- cursor?: string;
764
- }
765
-
766
- /* ── Flows ────────────────────────────────────────────────────────────────── */
767
-
768
- export type FlowStatus = "open" | "complete" | "cancelled";
769
- export type FlowMemberKind = "approval" | "review" | "collection" | "report";
770
-
771
- export interface FlowMember {
772
- kind: FlowMemberKind;
773
- id: string;
774
- title: string;
775
- /** The member's own status word, which differs by kind. */
776
- status: string;
777
- /** Still waiting on somebody. Always false for a report. */
778
- open: boolean;
779
- createdAt: string;
780
- }
781
-
782
- /** One line of the history: what happened, who did it, when. */
783
- export interface FlowEvent {
784
- event: string;
785
- actor: string;
786
- actorType: string;
787
- resourceType: string | null;
788
- resourceId: string | null;
789
- at: string;
790
- }
791
-
792
- export interface FlowData {
793
- id: string;
794
- status: FlowStatus;
795
- /** The timeline page a person can open. */
796
- url: string;
797
- title: string;
798
- description: string | null;
799
- externalId: string | null;
800
- metadata: Record<string, unknown>;
801
- startedBy: string;
802
- members: FlowMember[];
803
- memberCount: number;
804
- openCount: number;
805
- /** Nothing outstanding right now — not a claim that the job is finished. */
806
- allSettled: boolean;
807
- /** Present on a single read, absent from a list. */
808
- timeline?: FlowEvent[];
809
- settledAt: string | null;
810
- createdAt: string;
811
- }
812
-
813
- export interface CreateFlowInput {
814
- /** What this piece of work is, as the timeline will be titled. */
815
- title: string;
816
- /** What it is for, for whoever reads the history a year from now. */
817
- description?: string;
818
- workspaceId?: string;
819
- /** Your own reference. Pass it and use `resume()` so a restart does not start a second flow. */
820
- externalId?: string;
821
- metadata?: Record<string, unknown>;
822
- }
823
-
824
- export interface ListFlowsInput {
825
- status?: FlowStatus;
826
- externalId?: string;
827
- /** One page of this size. Leave it unset to get every row. */
828
- limit?: number;
829
- /** `nextCursor` from a previous page. Only meaningful with `limit`. */
830
- cursor?: string;
831
- }
832
-
833
- /* ── Evidence ─────────────────────────────────────────────────────────────── */
834
-
835
- export type EvidenceStepKind = "approval" | "review" | "collection" | "report";
836
-
837
- export interface EvidenceOutcome {
838
- who: string;
839
- /** What they said, in the words the step uses: "approved", "answered". */
840
- said: string;
841
- note: string | null;
842
- at: string;
843
- }
844
-
845
- export interface EvidenceStep {
846
- kind: EvidenceStepKind;
847
- id: string;
848
- title: string;
849
- status: string;
850
- url: string;
851
- createdAt: string;
852
- settledAt: string | null;
853
- requestedBy: string;
854
- /** Whether an agent asked for this, which is the point of the record. */
855
- requestedByAgent: boolean;
856
- asked: string[];
857
- outcomes: EvidenceOutcome[];
858
- /** Whatever else the step records: the description, the questions, the answers. */
859
- detail: Record<string, unknown>;
860
- }
861
-
862
- export interface EvidenceEvent {
863
- at: string;
864
- event: string;
865
- actor: string;
866
- actorType: string;
867
- /** Which step it happened to, when it happened to one. */
868
- step: string | null;
869
- metadata: Record<string, unknown>;
870
- }
871
-
872
- export interface EvidencePack {
873
- packVersion: number;
874
- generatedAt: string;
875
- generatedBy: string;
876
- organisation: { id: string; name: string };
877
- subject: {
878
- kind: "flow" | "report";
879
- id: string;
880
- title: string;
881
- url: string;
882
- status: string;
883
- startedBy: string;
884
- startedAt: string;
885
- };
886
- summary: {
887
- steps: number;
888
- events: number;
889
- firstEventAt: string | null;
890
- lastEventAt: string | null;
891
- };
892
- steps: EvidenceStep[];
893
- timeline: EvidenceEvent[];
894
- /**
895
- * What the digest does and does not stand for, in the pack's own words.
896
- *
897
- * `covers` says it detects a file altered after export. `doesNotCover` says
898
- * it makes no claim about the database. Both travel with the pack rather
899
- * than living only in documentation, because a reader who sees a hash and
900
- * no sentence will assume the stronger one.
901
- */
902
- integrity: {
903
- algorithm: "sha256";
904
- digest: string;
905
- covers: string;
906
- doesNotCover: string;
907
- recordsAreInsertOnly: boolean;
908
- };
909
- }
910
-
911
- /**
912
- * What arrives at a request's `callbackUrl`.
913
- *
914
- * `data` is the same object an organisation webhook carries for the event.
915
- * `approval.question` means the approver asked something and is waiting on
916
- * your answer (`answerQuestion`); every other event is the request settling.
917
- */
918
- export interface CallbackEnvelope {
919
- event:
920
- | "approval.approved"
921
- | "approval.rejected"
922
- | "approval.expired"
923
- | "approval.question"
924
- | "review.approved"
925
- | "review.changes_requested"
926
- | "review.expired"
927
- | "collection.completed"
928
- | "collection.expired";
929
- sentAt: string;
930
- requestType: "approval" | "review" | "collection";
931
- requestId: string;
932
- data: Record<string, unknown>;
933
- }
1
+ /**
2
+ * The API's objects, by hand.
3
+ *
4
+ * Not imported from the server's zod schemas on purpose: this package is
5
+ * published to npm and must not drag the monorepo's internals with it. The
6
+ * cost of that is drift, so `apps/web/src/lib/services/api-approvals.test.ts`
7
+ * holds these shapes to the schemas the API actually validates — a field added
8
+ * there and not here fails the build on the server side, where someone is
9
+ * looking.
10
+ */
11
+
12
+ export type ApprovalStatus = "pending" | "approved" | "rejected" | "changes_requested" | "expired" | "cancelled";
13
+ export type ApprovalRisk = "low" | "medium" | "high" | "critical";
14
+
15
+ /**
16
+ * What a gate decision can be.
17
+ *
18
+ * Seven, and the extra four over `allowed | denied | pending` are worth the
19
+ * width. `allowed` and `denied` are what a *rule* said; the rest are what a
20
+ * *person* did about a request no rule settled. An action that went through
21
+ * because policy permitted it and one that went through because somebody
22
+ * agreed to it are not the same fact — the ratio between them is the number
23
+ * this whole layer exists to make computable — so collapsing them would throw
24
+ * away the distinction at the one place a caller can see it.
25
+ */
26
+ export type GateStatus =
27
+ | "allowed"
28
+ | "denied"
29
+ | "pending"
30
+ | "approved"
31
+ | "rejected"
32
+ | "changes_requested"
33
+ | "expired"
34
+ | "cancelled"
35
+ /** A person took the permission back before it was used. */
36
+ | "revoked"
37
+ /** The permission has been used. A further act needs a new gate. */
38
+ | "used";
39
+
40
+ /** What a person decided about a gate, once one has. */
41
+ export type GateOutcomeName = "approved" | "rejected" | "changes_requested" | "cancelled" | "expired";
42
+
43
+ /**
44
+ * What policy said, in the words agents are told: fixed when the gate is made.
45
+ * `status` is where it stands now; this is what it was.
46
+ */
47
+ export type GateDecisionName = "ALLOW" | "APPROVAL_REQUIRED" | "REVIEW_REQUIRED" | "DENY";
48
+
49
+ /** Where an act lands. Deliverd decides whether it is inside the organisation. */
50
+ export interface Destination {
51
+ /** `workspace`, `report`, `user`, `group`, `email`, `url`, `channel`, `repository`, … */
52
+ type: string;
53
+ id: string;
54
+ label?: string;
55
+ }
56
+
57
+ /**
58
+ * What an act is about. A Deliverd report version (the approval binds to that
59
+ * version and no other), or a file you hold, by its sha256.
60
+ */
61
+ export interface GateArtifactRef {
62
+ reportId?: string;
63
+ versionId?: string;
64
+ sha256?: string;
65
+ name?: string;
66
+ mimeType?: string;
67
+ size?: number;
68
+ uri?: string;
69
+ }
70
+
71
+ /** Who is asking, when you ask through a person's connection rather than an agent key. */
72
+ export interface GateAgentRef {
73
+ /** A Deliverd agent id. */
74
+ id?: string;
75
+ /** `openai_dot`, `openai_chatgpt`, `openai_codex`, `anthropic`, `google`, `custom`, … */
76
+ provider?: string;
77
+ /** Your id on that platform. */
78
+ externalId?: string;
79
+ name?: string;
80
+ }
81
+
82
+ /** The run a gate belongs to, found by its id or started. */
83
+ export interface GateExecutionRef {
84
+ providerExecutionId?: string;
85
+ objective?: string;
86
+ title?: string;
87
+ /** The run that delegated this one. */
88
+ parentFlowId?: string;
89
+ }
90
+
91
+ /** What a gate's permission covers. Every field is fixed when the gate is made. */
92
+ export interface GateScope {
93
+ destination: Destination | null;
94
+ /** Worked out by Deliverd, never taken from the request. */
95
+ recipientScope: "internal" | "external" | null;
96
+ classification: "public" | "internal" | "confidential" | "restricted" | null;
97
+ risk: ApprovalRisk | null;
98
+ artifact: {
99
+ kind: "report_version" | "external";
100
+ reportId: string | null;
101
+ versionId: string | null;
102
+ versionNumber: number | null;
103
+ sha256: string | null;
104
+ name: string | null;
105
+ mimeType: string | null;
106
+ size: number | null;
107
+ uri: string | null;
108
+ /** True when Deliverd holds the artifact and the hash is its own. */
109
+ verified: boolean;
110
+ } | null;
111
+ digest: string | null;
112
+ }
113
+
114
+ /**
115
+ * A receipt: what the agent reported doing with a permission, and how much of
116
+ * it Deliverd checked. `verified` only when Deliverd did the act itself;
117
+ * `hash_matched` when it checked the hash; otherwise `reported`.
118
+ */
119
+ export interface ExecutionReceipt {
120
+ id: string;
121
+ gateId: string;
122
+ phase: "started" | "completed" | "failed";
123
+ claimId: string | null;
124
+ executedAt: string | null;
125
+ artifactSha256: string | null;
126
+ destination: Destination | null;
127
+ result: Record<string, unknown>;
128
+ verification: "verified" | "hash_matched" | "reported";
129
+ detail: string | null;
130
+ reportedBy: string;
131
+ createdAt: string;
132
+ }
133
+
134
+ /** What you tell Deliverd you did. Recorded as your report, never as verified fact. */
135
+ export interface RecordExecutionInput {
136
+ /** `started` claims a use before you act; `completed` (the default) or `failed` reports the outcome. */
137
+ phase?: "started" | "completed" | "failed";
138
+ /** The id of your `started` receipt, when this finishes it. */
139
+ claimId?: string;
140
+ executedAt?: string;
141
+ /** Required when the permission names an artifact; a different hash is refused. */
142
+ artifactSha256?: string;
143
+ /** Where it landed. Must be where it was authorised to. */
144
+ destination?: Destination;
145
+ result?: Record<string, unknown>;
146
+ detail?: string;
147
+ agent?: GateAgentRef;
148
+ }
149
+
150
+ export interface CreateGateInput {
151
+ /** The registered action you are about to perform: `finance.refund`. */
152
+ actionId: string;
153
+ /** The arguments you will actually execute with. Validated against the action's schema. */
154
+ input: Record<string, unknown>;
155
+ /**
156
+ * Your id for this unit of work — `refund:ord_8812`. **Required**, which no
157
+ * other create in this SDK is.
158
+ *
159
+ * Every other POST mints a random idempotency key per attempt, which guards a
160
+ * retried *request*. This guards a retried *decision*: a crashed agent that
161
+ * re-runs its refund step must re-read the answer it already got, not ask a
162
+ * second person about the same money. No id the SDK invented could know which
163
+ * two calls are the same attempt, so you name it.
164
+ */
165
+ externalId: string;
166
+ /** Where this is running, for rules that tell staging from production. */
167
+ environment?: string;
168
+ /** Why, shown to whoever is asked to decide. */
169
+ reason?: string;
170
+ flowId?: string;
171
+ /** What you are about to do, in a sentence a person will read. Same as `reason`. */
172
+ description?: string;
173
+ /** Where the act lands. An approval covers this destination and no other. */
174
+ destination?: Destination;
175
+ /** How sensitive the data is. Raises, never lowers, what Deliverd knows. */
176
+ classification?: "public" | "internal" | "confidential" | "restricted";
177
+ /** How risky you judge it. Raises, never lowers, the action's own risk. */
178
+ risk?: ApprovalRisk;
179
+ /** What the act is about. An approval covers this artifact and no other. */
180
+ artifact?: GateArtifactRef;
181
+ /** Who you are, when you ask through a person's connection. */
182
+ agent?: GateAgentRef;
183
+ /** The run this belongs to. Use instead of flowId. */
184
+ execution?: GateExecutionRef;
185
+ /** The gate this revises, after a person asked for changes. */
186
+ supersedesGateId?: string;
187
+ /** An https address for the gate's settlement and execution, signed. */
188
+ callbackUrl?: string;
189
+ /** Anything else a person deciding should see. Read by no rule. */
190
+ metadata?: Record<string, unknown>;
191
+ }
192
+
193
+ export interface GateData {
194
+ id: string;
195
+ status: GateStatus;
196
+ /** The one to branch on: a rule permitted it, or a person agreed to it. */
197
+ allowed: boolean;
198
+ /**
199
+ * What to execute with: the input as the action's schema validated it, or
200
+ * the approver's correction of it when they approved with changes.
201
+ */
202
+ input: Record<string, unknown>;
203
+ /** What the approver changed in it. Empty unless they did. */
204
+ changes: FieldChange[];
205
+ /**
206
+ * What the organisation's ethics rules asked whoever decides to weigh, as
207
+ * they read when this was asked. Empty when nothing matched. A flagged
208
+ * request is approved with a written reason, never from a sign-in-free link.
209
+ */
210
+ concerns: { principle: string; rule: string; concern: string }[];
211
+ /** Whether a rule decided this or a person did. */
212
+ basis: "policy" | "human";
213
+ reason: string | null;
214
+ /** The rule that decided, by name. Null when nothing matched. */
215
+ rule: string | null;
216
+ policyVersionId: string | null;
217
+ approvalId: string | null;
218
+ approvalUrl: string | null;
219
+ outcome: GateOutcomeName | null;
220
+ settledAt: string | null;
221
+ /** True when this call found a decision already made under your `externalId`. */
222
+ reused: boolean;
223
+ /** What policy said, fixed when the gate was made. */
224
+ decision: GateDecisionName;
225
+ /**
226
+ * Whether you may act on this now: authorised, inside its window, with a use
227
+ * left, not revoked. `allowed` says it was ever authorised; this says it
228
+ * still is. The organisation's authorisation only — the platform you run on
229
+ * may still require its user's confirmation.
230
+ */
231
+ canExecute: boolean;
232
+ /** Why not, when `canExecute` is false. */
233
+ blockedBecause: string | null;
234
+ scope: GateScope;
235
+ authorisation: { validUntil: string | null; maxUses: number; usesRemaining: number };
236
+ actionId: string;
237
+ agentId: string | null;
238
+ flowId: string | null;
239
+ supersedesGateId: string | null;
240
+ description: string | null;
241
+ requestedBy: string;
242
+ createdAt: string | null;
243
+ /** Returned once, by the call that made the gate and named a callbackUrl. */
244
+ callbackSecret?: string;
245
+ /** On a single read: what has been reported against it. */
246
+ executions?: ExecutionReceipt[];
247
+ }
248
+
249
+ /**
250
+ * The answer, flattened — what `gate()` hands back.
251
+ *
252
+ * `allowed` is a boolean so `if (decision.allowed)` reads as the sentence it
253
+ * is; `status` is the narrowing union for a switch. The same pairing, for the
254
+ * same reason, as `Decision` on an approval.
255
+ */
256
+ export interface GateDecision {
257
+ allowed: boolean;
258
+ status: GateStatus;
259
+ reason: string | null;
260
+ rule: string | null;
261
+ /** What to execute with, corrections included. */
262
+ input: Record<string, unknown>;
263
+ /** What the approver changed. Empty unless they did. */
264
+ changes: FieldChange[];
265
+ id: string;
266
+ approvalUrl: string | null;
267
+ gate: unknown;
268
+ }
269
+
270
+ /** One field an approver corrected before approving. */
271
+ export interface FieldChange {
272
+ field: string;
273
+ from: unknown;
274
+ to: unknown;
275
+ }
276
+
277
+ /** One line of evidence, as the approval page shows it. */
278
+ export interface ApprovalFactor {
279
+ label: string;
280
+ status?: "ok" | "warning" | "info";
281
+ detail?: string;
282
+ }
283
+
284
+ export interface ApprovalLink {
285
+ label: string;
286
+ url: string;
287
+ }
288
+
289
+ export interface ApprovalQuestion {
290
+ id: string;
291
+ question: string;
292
+ answer: string | null;
293
+ askedAt: string;
294
+ answeredAt: string | null;
295
+ }
296
+
297
+ export interface ApprovalData {
298
+ id: string;
299
+ status: ApprovalStatus;
300
+ /** The page the approver decides on. */
301
+ url: string;
302
+ title: string;
303
+ description: string | null;
304
+ risk: ApprovalRisk;
305
+ factors: ApprovalFactor[];
306
+ links: ApprovalLink[];
307
+ reportId: string | null;
308
+ externalId: string | null;
309
+ metadata: Record<string, unknown>;
310
+ /** What you proposed to run with, unchanged. */
311
+ input: Record<string, unknown> | null;
312
+ /** Which fields of it the approver may correct. */
313
+ editableFields: string[];
314
+ /** What to run with once approved: `input` with any corrections. Null until then. */
315
+ approvedInput: Record<string, unknown> | null;
316
+ /** What the approver changed. */
317
+ changes: FieldChange[];
318
+ /**
319
+ * What the organisation's ethics rules asked whoever decides to weigh, as
320
+ * they read when this was asked. Empty when nothing matched. A flagged
321
+ * request is approved with a written reason, never from a sign-in-free link.
322
+ */
323
+ concerns: { principle: string; rule: string; concern: string }[];
324
+ requestedBy: string;
325
+ approvers: string[];
326
+ /**
327
+ * How many people must agree before it settles. One unless a standing rule
328
+ * in the organisation escalated it — an agent cannot set this, and a rule
329
+ * can only push it up.
330
+ */
331
+ requiredApprovals: number;
332
+ /** How many have approved so far. Compare with `requiredApprovals`. */
333
+ approvalsSoFar: number;
334
+ /** Who decided, as a name rather than an id — the same as a review's `by`. */
335
+ decidedBy: string | null;
336
+ /** Their user id, for anything that needs the key rather than the person. */
337
+ decidedById: string | null;
338
+ decidedAt: string | null;
339
+ /** The approver's reason, on a rejection or an approval that carried one. */
340
+ note: string | null;
341
+ expiresAt: string | null;
342
+ questions: ApprovalQuestion[];
343
+ createdAt: string;
344
+ }
345
+
346
+ export interface CreateApprovalInput {
347
+ /** What is being asked, as a headline. */
348
+ title: string;
349
+ /** Why, what it affects, what it costs — what the approver reads first. */
350
+ description?: string;
351
+ /** How the approver should weigh it. Medium when omitted. */
352
+ risk?: ApprovalRisk;
353
+ /** Evidence, one line each, shown as a checklist. */
354
+ factors?: ApprovalFactor[];
355
+ /** Where to read more. */
356
+ links?: ApprovalLink[];
357
+ /** A published report the request is about. */
358
+ reportId?: string;
359
+ /**
360
+ * Who may decide. Each entry is a person — an email or a user id — or the
361
+ * name of a directory group or workspace, or a word meaning the whole
362
+ * organisation ("everyone"). Naming a team is usually what you want: a
363
+ * request addressed to one person waits for that person to come back from
364
+ * holiday, and anyone on a team can answer.
365
+ *
366
+ * The organisation's owners and admins decide when this is omitted. You
367
+ * cannot name only yourself; being *on* a team you address is fine and means
368
+ * the rest of it. A name matching both a person and a team is refused rather
369
+ * than guessed — name it by id.
370
+ */
371
+ approvers?: string[];
372
+ /** After this the request expires undecided. ISO 8601. */
373
+ expiresAt?: string;
374
+ /** Your own reference, returned unchanged and searchable. */
375
+ externalId?: string;
376
+ /**
377
+ * The flow this belongs to, when it is one step of a larger piece of work.
378
+ * Must be an open flow in your organisation. `flow.approve()` and its
379
+ * siblings set this for you.
380
+ */
381
+ flowId?: string;
382
+ /**
383
+ * Where to POST the outcome when a person answers, instead of polling:
384
+ * HTTPS, and a public address. The call that makes the request returns the
385
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
386
+ */
387
+ callbackUrl?: string;
388
+ metadata?: Record<string, unknown>;
389
+ /**
390
+ * The arguments you will run with if this is approved, shown to the
391
+ * approver. The decision's `input` is what to actually run with.
392
+ */
393
+ input?: Record<string, unknown>;
394
+ /**
395
+ * Fields of `input` the approver may correct before approving: strings,
396
+ * numbers and true/false. Omitted, it is approve or reject only.
397
+ */
398
+ editableFields?: string[];
399
+ }
400
+
401
+ /**
402
+ * The answer to `approve()`.
403
+ *
404
+ * Flat on purpose: the line after the call is `if (decision.approved)`, and
405
+ * anything a caller has to reach through to get there is a step this SDK
406
+ * exists to remove. The whole request is on `approval` when a field here does
407
+ * not cover it.
408
+ */
409
+ export type Decision = {
410
+ /** True only for an approval. False for rejected, changes requested, expired and cancelled. */
411
+ approved: boolean;
412
+ /** For a switch, and for narrowing. */
413
+ status: "approved" | "rejected" | "changes_requested" | "expired" | "cancelled";
414
+ /** Their reason, when they gave one. */
415
+ note: string | null;
416
+ /** Who decided, as a name rather than an id. Log it; put it in a message. */
417
+ decidedBy: string | null;
418
+ /** Their user id, when the key is what you need. */
419
+ decidedById: string | null;
420
+ decidedAt: string | null;
421
+ id: string;
422
+ /** The page they decided on. Worth logging. */
423
+ url: string;
424
+ /**
425
+ * What to run with, when you sent an `input` and it was approved: yours,
426
+ * with any corrections the approver made. Null otherwise — never run the
427
+ * proposal when this is null.
428
+ */
429
+ input: Record<string, unknown> | null;
430
+ /** What the approver changed. Empty when they approved it as proposed. */
431
+ changes: FieldChange[];
432
+ /** The request itself, for anything the fields above do not name. */
433
+ approval: unknown;
434
+ };
435
+
436
+ export interface ListApprovalsInput {
437
+ status?: ApprovalStatus;
438
+ externalId?: string;
439
+ /** One page of this size. Leave it unset to get every row. */
440
+ limit?: number;
441
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
442
+ cursor?: string;
443
+ }
444
+
445
+ /* ── Reports ─────────────────────────────────────────────────────────────── */
446
+
447
+ export interface InlineFile {
448
+ path: string;
449
+ content: string;
450
+ /** `base64` for an image or a font; text otherwise. */
451
+ encoding?: "utf8" | "base64";
452
+ }
453
+
454
+ export interface PublishReportInput {
455
+ title?: string;
456
+ slug?: string;
457
+ description?: string;
458
+ workspaceId?: string;
459
+ /** Names, teams, groups or emails — resolved server-side. */
460
+ audience?: unknown;
461
+ classification?: string;
462
+ living?: boolean;
463
+ sourceTool?: string;
464
+ sourceModel?: string;
465
+ changeSummary?: string;
466
+ /** Publish only if this is still the current version; 0 claims a new slug. */
467
+ expectedVersion?: number;
468
+ uploadId?: string;
469
+ content?: string;
470
+ files?: InlineFile[];
471
+ }
472
+
473
+ export type UpdateReportInput = Pick<
474
+ PublishReportInput,
475
+ | "uploadId"
476
+ | "content"
477
+ | "files"
478
+ | "title"
479
+ | "description"
480
+ | "sourceTool"
481
+ | "sourceModel"
482
+ | "changeSummary"
483
+ | "expectedVersion"
484
+ >;
485
+
486
+ export interface ReportData {
487
+ id: string;
488
+ slug: string;
489
+ title: string;
490
+ url: string;
491
+ status: string;
492
+ currentVersion: number | null;
493
+ [key: string]: unknown;
494
+ }
495
+
496
+ /**
497
+ * A publish held by a policy rule answers 202 with this instead of going live.
498
+ * `status` says which happened, so a caller that ignores it still gets a
499
+ * report object and a caller that reads it knows nobody can see the thing yet.
500
+ */
501
+ export interface PublishResult {
502
+ status?: "published" | "updated" | "pending_approval";
503
+ report: ReportData;
504
+ version?: { id: string; versionNumber: number; [key: string]: unknown };
505
+ approval?: { id: string; status: string };
506
+ warnings?: string[];
507
+ [key: string]: unknown;
508
+ }
509
+
510
+ /**
511
+ * One open thread, as the organisation-wide list returns it.
512
+ *
513
+ * Deliberately thinner than a `CommentThread`: this answers "where is the
514
+ * feedback" across every report, so it carries the report and the quoted
515
+ * passage rather than the whole conversation. Fetch the thread itself with
516
+ * `comments.list(reportId)` once you know which report to look at.
517
+ */
518
+ export interface OpenThread {
519
+ threadId: string;
520
+ reportId: string;
521
+ reportTitle: string;
522
+ reportSlug: string;
523
+ /** Who owns the report — filter on it to find the threads on yours. */
524
+ reportOwnerId: string | null;
525
+ quote: string | null;
526
+ author: string;
527
+ authorType: string;
528
+ messages: number;
529
+ lastActivityAt: string;
530
+ }
531
+
532
+ /**
533
+ * What a send did, per address.
534
+ *
535
+ * `delivered` is the mail provider accepting it, not the person reading it —
536
+ * and `alreadyHadAccess` names the recipients who could already open the
537
+ * report, who were emailed again anyway. Re-sending to somebody who says
538
+ * they never got the first one is the point.
539
+ */
540
+ export interface SendResult {
541
+ sent: { email: string; delivered: boolean }[];
542
+ alreadyHadAccess: string[];
543
+ }
544
+
545
+ /* ── Schedules ───────────────────────────────────────────────────────────── */
546
+
547
+ /**
548
+ * A recurring publish an agent is expected to perform.
549
+ *
550
+ * `due` is the useful field: true once the schedule has fired and nobody has
551
+ * acted on that firing. Publishing a new version clears it, and so does
552
+ * writing a dataset — for a report that reads its numbers from `_data/…`,
553
+ * updating the data is the whole job.
554
+ */
555
+ export interface ScheduleSummary {
556
+ id: string;
557
+ reportId: string;
558
+ reportSlug: string;
559
+ reportTitle: string;
560
+ reportUrl: string;
561
+ agentId: string;
562
+ agentName: string;
563
+ /** Five-field cron expression, evaluated in UTC. */
564
+ recurrence: string;
565
+ enabled: boolean;
566
+ lastRunAt: string | null;
567
+ nextRunAt: string | null;
568
+ currentVersion: number | null;
569
+ due: boolean;
570
+ dueSince: string | null;
571
+ }
572
+
573
+ /* ── Comments ────────────────────────────────────────────────────────────── */
574
+
575
+ export interface CommentThread {
576
+ threadId: string;
577
+ status: "open" | "resolved";
578
+ quote: string | null;
579
+ messages: {
580
+ /** What `comments.retract` takes. */
581
+ commentId: string;
582
+ author: string;
583
+ authorType: string;
584
+ body: string;
585
+ createdAt: string;
586
+ /** True for the one message this credential could still take back. */
587
+ retractable: boolean;
588
+ }[];
589
+ [key: string]: unknown;
590
+ }
591
+
592
+ /* ── Analytics ───────────────────────────────────────────────────────────── */
593
+
594
+ /** Who read one report. The detail beyond `totalViews` needs the analytics plan. */
595
+ export interface ReportAnalytics {
596
+ reportId: string;
597
+ title: string;
598
+ totalViews: number;
599
+ uniqueViewers: number | null;
600
+ internalViewers: number | null;
601
+ externalViewers: number | null;
602
+ firstViewedAt: string | null;
603
+ lastViewedAt: string | null;
604
+ byDay: { day: string; views: number; uniqueViewers: number }[];
605
+ byVersion: {
606
+ versionNumber: number;
607
+ views: number;
608
+ uniqueViewers: number;
609
+ lastViewedAt: string | null;
610
+ }[];
611
+ /** Names only where the organisation shows viewer identities. */
612
+ recentViewers: {
613
+ displayName: string;
614
+ principalType: string;
615
+ viewCount: number;
616
+ lastViewedAt: string;
617
+ }[];
618
+ }
619
+
620
+ /** What is being read across every report, and what is not being read at all. */
621
+ export interface OrgAnalytics {
622
+ days: number;
623
+ totalViews: number;
624
+ uniqueViewers: number;
625
+ activeReports: number;
626
+ externallySharedReports: number;
627
+ publicReports: number;
628
+ publishesInPeriod: number;
629
+ topReports: {
630
+ reportId: string;
631
+ title: string;
632
+ views: number;
633
+ uniqueViewers: number;
634
+ lastViewedAt: string | null;
635
+ }[];
636
+ /** Live reports with no view in the period — oldest silence first. */
637
+ inactiveReports: {
638
+ reportId: string;
639
+ title: string;
640
+ lastViewedAt: string | null;
641
+ publishedAt: string | null;
642
+ }[];
643
+ }
644
+
645
+ /* ── Webhooks ────────────────────────────────────────────────────────────── */
646
+
647
+ export type WebhookEventName =
648
+ | "report.published"
649
+ | "report.updated"
650
+ | "report.shared"
651
+ | "report.viewed"
652
+ | "comment.created"
653
+ | "access.requested"
654
+ | "schedule.due"
655
+ | "publish.held"
656
+ | "approval.requested"
657
+ | "approval.approved"
658
+ | "approval.rejected"
659
+ | "approval.changes_requested"
660
+ | "approval.expired"
661
+ | "approval.escalated"
662
+ | "approval.question"
663
+ | "approval.answered"
664
+ | "review.requested"
665
+ | "review.approved"
666
+ | "review.changes_requested"
667
+ | "collection.requested"
668
+ | "collection.completed"
669
+ | "flow.completed"
670
+ /** A gate refused. The only gate event that relays: an allow fires on every
671
+ * auto-allowed action, and an escalation already arrives as
672
+ * `approval.requested`. */
673
+ | "gate.denied"
674
+ /** A gate's whole life. Opt-in: sent only to an endpoint that names them. */
675
+ | "gate.created"
676
+ | "gate.approved"
677
+ | "gate.rejected"
678
+ | "gate.changes_requested"
679
+ | "gate.expired"
680
+ | "gate.cancelled"
681
+ | "gate.revoked"
682
+ | "gate.executed";
683
+
684
+ export interface WebhookEvent {
685
+ event: WebhookEventName;
686
+ sentAt: string;
687
+ /** Present and true when sent by the Send test button, not by real activity. */
688
+ test?: boolean;
689
+ data: Record<string, unknown>;
690
+ }
691
+
692
+ /* ── Reviews ──────────────────────────────────────────────────────────────── */
693
+
694
+ export type ReviewStatus =
695
+ | "pending"
696
+ | "approved"
697
+ | "changes_requested"
698
+ | "expired"
699
+ | "cancelled";
700
+
701
+ export interface CreateReviewInput {
702
+ /** What is being reviewed, as a headline the reviewer sees first. */
703
+ title: string;
704
+ /**
705
+ * What to check. Without this a reviewer decides what "review" means, and
706
+ * usually decides it means "looks fine".
707
+ */
708
+ instructions?: string;
709
+ /** The published report under review; the reviewer reads it and comments on it. */
710
+ reportId?: string;
711
+ /** Pin a version, so publishing again mid-review does not move the ground. */
712
+ versionId?: string;
713
+ /**
714
+ * Emails or user ids. An active member, or a guest who can already open the
715
+ * report — anyone else is refused rather than emailed. You cannot name
716
+ * yourself.
717
+ */
718
+ reviewers: string[];
719
+ /**
720
+ * How many approvals settle it; one when omitted. A single "changes
721
+ * requested" settles it regardless.
722
+ */
723
+ requiredApprovals?: number;
724
+ /** After this the review expires unanswered. ISO 8601. */
725
+ expiresAt?: string;
726
+ /** Your own reference, returned unchanged and searchable. */
727
+ externalId?: string;
728
+ /**
729
+ * The flow this belongs to, when it is one step of a larger piece of work.
730
+ * Must be an open flow in your organisation. `flow.approve()` and its
731
+ * siblings set this for you.
732
+ */
733
+ flowId?: string;
734
+ /**
735
+ * Where to POST the outcome when a person answers, instead of polling:
736
+ * HTTPS, and a public address. The call that makes the request returns the
737
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
738
+ */
739
+ callbackUrl?: string;
740
+ metadata?: Record<string, unknown>;
741
+ }
742
+
743
+ export interface ReviewerRef {
744
+ kind: "user" | "guest";
745
+ id: string;
746
+ label: string;
747
+ }
748
+
749
+ export interface ReviewVerdict {
750
+ verdict: "approved" | "changes_requested";
751
+ /** Who gave it, as a name rather than an id. */
752
+ by: string;
753
+ note: string | null;
754
+ at: string;
755
+ }
756
+
757
+ export interface ReviewData {
758
+ id: string;
759
+ status: ReviewStatus;
760
+ /** The page the reviewer reads and decides on. */
761
+ url: string;
762
+ title: string;
763
+ instructions: string | null;
764
+ reportId: string | null;
765
+ versionId: string | null;
766
+ externalId: string | null;
767
+ metadata: Record<string, unknown>;
768
+ requestedBy: string;
769
+ requiredApprovals: number;
770
+ reviewers: ReviewerRef[];
771
+ verdicts: ReviewVerdict[];
772
+ /** How many comment threads the reviewers opened while reading. */
773
+ threadCount: number;
774
+ settledAt: string | null;
775
+ expiresAt: string | null;
776
+ createdAt: string;
777
+ }
778
+
779
+ /** The answer, flattened — what `review()` hands back. */
780
+ export interface ReviewOutcome {
781
+ /** The one to branch on. False for changes requested, expired and cancelled. */
782
+ approved: boolean;
783
+ status: Exclude<ReviewStatus, "pending">;
784
+ /** Every verdict returned, in the order they arrived. */
785
+ verdicts: ReviewVerdict[];
786
+ /** How many comment threads to read before producing the next version. */
787
+ threadCount: number;
788
+ id: string;
789
+ url: string;
790
+ review: ReviewData;
791
+ }
792
+
793
+ export interface ListReviewsInput {
794
+ status?: ReviewStatus;
795
+ externalId?: string;
796
+ reportId?: string;
797
+ /** One page of this size. Leave it unset to get every row. */
798
+ limit?: number;
799
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
800
+ cursor?: string;
801
+ }
802
+
803
+ /* ── Collections ──────────────────────────────────────────────────────────── */
804
+
805
+ export type CollectionStatus = "pending" | "complete" | "expired" | "cancelled";
806
+
807
+ export type QuestionKind =
808
+ | "text"
809
+ | "long_text"
810
+ | "number"
811
+ | "date"
812
+ | "choice"
813
+ | "multi_choice"
814
+ | "boolean";
815
+
816
+ /** What an answer can hold, shaped by its question's kind. */
817
+ export type AnswerValue = string | number | boolean | string[];
818
+
819
+ export interface QuestionInput {
820
+ /** The question, as you would ask it out loud. */
821
+ prompt: string;
822
+ /** The sentence under the field that stops the wrong answer being given. */
823
+ help?: string;
824
+ kind: QuestionKind;
825
+ /** Required unless you say otherwise; a required question blocks submission. */
826
+ required?: boolean;
827
+ /** For `choice` and `multi_choice`. At least two, or it is not a question. */
828
+ options?: string[];
829
+ }
830
+
831
+ export interface CreateCollectionInput {
832
+ /** What you need, as a headline the person sees first. */
833
+ title: string;
834
+ /** Why you are asking, shown above the questions. */
835
+ instructions?: string;
836
+ questions: QuestionInput[];
837
+ /**
838
+ * Emails or user ids. An active member, or a guest the organisation already
839
+ * knows — anyone else is refused rather than emailed.
840
+ */
841
+ respondents: string[];
842
+ /** How many submitted replies complete it; everyone asked, when omitted. */
843
+ requiredResponses?: number;
844
+ /** A published report the request is about. */
845
+ reportId?: string;
846
+ /** Shown to the person, and what the single reminder is measured against. */
847
+ dueAt?: string;
848
+ /** After this the request closes unanswered. ISO 8601. */
849
+ expiresAt?: string;
850
+ externalId?: string;
851
+ /**
852
+ * The flow this belongs to, when it is one step of a larger piece of work.
853
+ * Must be an open flow in your organisation. `flow.approve()` and its
854
+ * siblings set this for you.
855
+ */
856
+ flowId?: string;
857
+ /**
858
+ * Where to POST the outcome when a person answers, instead of polling:
859
+ * HTTPS, and a public address. The call that makes the request returns the
860
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
861
+ */
862
+ callbackUrl?: string;
863
+ metadata?: Record<string, unknown>;
864
+ }
865
+
866
+ export interface CollectionQuestion {
867
+ id: string;
868
+ prompt: string;
869
+ help: string | null;
870
+ kind: QuestionKind;
871
+ required: boolean;
872
+ options: string[];
873
+ }
874
+
875
+ export interface CollectionReply {
876
+ /** Who answered, as a name rather than an id. */
877
+ respondent: string;
878
+ status: "pending" | "submitted";
879
+ submittedAt: string | null;
880
+ /** Empty until they submit: a half-typed draft is not what they meant to say. */
881
+ answers: { question: string; kind: QuestionKind; value: AnswerValue }[];
882
+ }
883
+
884
+ export interface CollectionData {
885
+ id: string;
886
+ status: CollectionStatus;
887
+ /** The page the person fills in. */
888
+ url: string;
889
+ title: string;
890
+ instructions: string | null;
891
+ reportId: string | null;
892
+ externalId: string | null;
893
+ metadata: Record<string, unknown>;
894
+ requestedBy: string;
895
+ requiredResponses: number;
896
+ questions: CollectionQuestion[];
897
+ responses: CollectionReply[];
898
+ submittedCount: number;
899
+ askedCount: number;
900
+ settledAt: string | null;
901
+ dueAt: string | null;
902
+ expiresAt: string | null;
903
+ createdAt: string;
904
+ }
905
+
906
+ /** The answers, flattened — what `collect()` hands back. */
907
+ export interface CollectedAnswers {
908
+ /** True when enough people replied; false if it expired or was withdrawn. */
909
+ complete: boolean;
910
+ status: Exclude<CollectionStatus, "pending">;
911
+ /** Every submitted reply, in the order they arrived. */
912
+ responses: CollectionReply[];
913
+ /**
914
+ * The first submitted answer to each question, by its prompt — the shape
915
+ * most callers want when they asked one person for three facts.
916
+ */
917
+ answers: Record<string, AnswerValue>;
918
+ id: string;
919
+ url: string;
920
+ collection: CollectionData;
921
+ }
922
+
923
+ export interface ListCollectionsInput {
924
+ status?: CollectionStatus;
925
+ externalId?: string;
926
+ /** One page of this size. Leave it unset to get every row. */
927
+ limit?: number;
928
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
929
+ cursor?: string;
930
+ }
931
+
932
+ /* ── Flows ────────────────────────────────────────────────────────────────── */
933
+
934
+ export type FlowStatus = "open" | "complete" | "cancelled";
935
+ export type FlowMemberKind = "approval" | "review" | "collection" | "report";
936
+
937
+ export interface FlowMember {
938
+ kind: FlowMemberKind;
939
+ id: string;
940
+ title: string;
941
+ /** The member's own status word, which differs by kind. */
942
+ status: string;
943
+ /** Still waiting on somebody. Always false for a report. */
944
+ open: boolean;
945
+ createdAt: string;
946
+ }
947
+
948
+ /** One line of the history: what happened, who did it, when. */
949
+ export interface FlowEvent {
950
+ event: string;
951
+ actor: string;
952
+ actorType: string;
953
+ resourceType: string | null;
954
+ resourceId: string | null;
955
+ at: string;
956
+ }
957
+
958
+ export interface FlowData {
959
+ id: string;
960
+ status: FlowStatus;
961
+ /** The timeline page a person can open. */
962
+ url: string;
963
+ title: string;
964
+ description: string | null;
965
+ externalId: string | null;
966
+ metadata: Record<string, unknown>;
967
+ startedBy: string;
968
+ members: FlowMember[];
969
+ memberCount: number;
970
+ openCount: number;
971
+ /** Nothing outstanding right now — not a claim that the job is finished. */
972
+ allSettled: boolean;
973
+ /** Present on a single read, absent from a list. */
974
+ timeline?: FlowEvent[];
975
+ settledAt: string | null;
976
+ createdAt: string;
977
+ }
978
+
979
+ export interface CreateFlowInput {
980
+ /** What this piece of work is, as the timeline will be titled. */
981
+ title: string;
982
+ /** What it is for, for whoever reads the history a year from now. */
983
+ description?: string;
984
+ workspaceId?: string;
985
+ /** Your own reference. Pass it and use `resume()` so a restart does not start a second flow. */
986
+ externalId?: string;
987
+ metadata?: Record<string, unknown>;
988
+ }
989
+
990
+ export interface ListFlowsInput {
991
+ status?: FlowStatus;
992
+ externalId?: string;
993
+ /** One page of this size. Leave it unset to get every row. */
994
+ limit?: number;
995
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
996
+ cursor?: string;
997
+ }
998
+
999
+ /* ── Evidence ─────────────────────────────────────────────────────────────── */
1000
+
1001
+ export type EvidenceStepKind = "approval" | "review" | "collection" | "report";
1002
+
1003
+ export interface EvidenceOutcome {
1004
+ who: string;
1005
+ /** What they said, in the words the step uses: "approved", "answered". */
1006
+ said: string;
1007
+ note: string | null;
1008
+ at: string;
1009
+ }
1010
+
1011
+ export interface EvidenceStep {
1012
+ kind: EvidenceStepKind;
1013
+ id: string;
1014
+ title: string;
1015
+ status: string;
1016
+ url: string;
1017
+ createdAt: string;
1018
+ settledAt: string | null;
1019
+ requestedBy: string;
1020
+ /** Whether an agent asked for this, which is the point of the record. */
1021
+ requestedByAgent: boolean;
1022
+ asked: string[];
1023
+ outcomes: EvidenceOutcome[];
1024
+ /** Whatever else the step records: the description, the questions, the answers. */
1025
+ detail: Record<string, unknown>;
1026
+ }
1027
+
1028
+ export interface EvidenceEvent {
1029
+ at: string;
1030
+ event: string;
1031
+ actor: string;
1032
+ actorType: string;
1033
+ /** Which step it happened to, when it happened to one. */
1034
+ step: string | null;
1035
+ metadata: Record<string, unknown>;
1036
+ }
1037
+
1038
+ export interface EvidencePack {
1039
+ packVersion: number;
1040
+ generatedAt: string;
1041
+ generatedBy: string;
1042
+ organisation: { id: string; name: string };
1043
+ subject: {
1044
+ kind: "flow" | "report";
1045
+ id: string;
1046
+ title: string;
1047
+ url: string;
1048
+ status: string;
1049
+ startedBy: string;
1050
+ startedAt: string;
1051
+ };
1052
+ summary: {
1053
+ steps: number;
1054
+ events: number;
1055
+ firstEventAt: string | null;
1056
+ lastEventAt: string | null;
1057
+ };
1058
+ steps: EvidenceStep[];
1059
+ timeline: EvidenceEvent[];
1060
+ /**
1061
+ * What the digest does and does not stand for, in the pack's own words.
1062
+ *
1063
+ * `covers` says it detects a file altered after export. `doesNotCover` says
1064
+ * it makes no claim about the database. Both travel with the pack rather
1065
+ * than living only in documentation, because a reader who sees a hash and
1066
+ * no sentence will assume the stronger one.
1067
+ */
1068
+ integrity: {
1069
+ algorithm: "sha256";
1070
+ digest: string;
1071
+ covers: string;
1072
+ doesNotCover: string;
1073
+ recordsAreInsertOnly: boolean;
1074
+ };
1075
+ }
1076
+
1077
+ /**
1078
+ * What arrives at a request's `callbackUrl`.
1079
+ *
1080
+ * `data` is the same object an organisation webhook carries for the event.
1081
+ * `approval.question` means the approver asked something and is waiting on
1082
+ * your answer (`answerQuestion`); every other event is the request settling.
1083
+ */
1084
+ export interface CallbackEnvelope {
1085
+ event:
1086
+ | "approval.approved"
1087
+ | "approval.rejected"
1088
+ | "approval.changes_requested"
1089
+ | "approval.expired"
1090
+ | "approval.question"
1091
+ | "review.approved"
1092
+ | "review.changes_requested"
1093
+ | "review.expired"
1094
+ | "collection.completed"
1095
+ | "collection.expired"
1096
+ | "gate.approved"
1097
+ | "gate.rejected"
1098
+ | "gate.changes_requested"
1099
+ | "gate.expired"
1100
+ | "gate.cancelled"
1101
+ | "gate.revoked"
1102
+ | "gate.executed";
1103
+ sentAt: string;
1104
+ requestType: "approval" | "review" | "collection" | "gate";
1105
+ requestId: string;
1106
+ data: Record<string, unknown>;
1107
+ }