@deliverd/sdk 0.11.1 → 0.13.0

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,1107 +1,1536 @@
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
- }
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
+ /** An objective finished. */
684
+ | "task.completed"
685
+ /** Opt-in: a task moved into blocked, or a side task finished and its
686
+ * result waits to be applied, kept or discarded. */
687
+ | "task.blocked"
688
+ | "side_task.completed";
689
+
690
+ export interface WebhookEvent {
691
+ event: WebhookEventName;
692
+ sentAt: string;
693
+ /** Present and true when sent by the Send test button, not by real activity. */
694
+ test?: boolean;
695
+ data: Record<string, unknown>;
696
+ }
697
+
698
+ /* ── Reviews ──────────────────────────────────────────────────────────────── */
699
+
700
+ export type ReviewStatus =
701
+ | "pending"
702
+ | "approved"
703
+ | "changes_requested"
704
+ | "expired"
705
+ | "cancelled";
706
+
707
+ export interface CreateReviewInput {
708
+ /** What is being reviewed, as a headline the reviewer sees first. */
709
+ title: string;
710
+ /**
711
+ * What to check. Without this a reviewer decides what "review" means, and
712
+ * usually decides it means "looks fine".
713
+ */
714
+ instructions?: string;
715
+ /** The published report under review; the reviewer reads it and comments on it. */
716
+ reportId?: string;
717
+ /** Pin a version, so publishing again mid-review does not move the ground. */
718
+ versionId?: string;
719
+ /**
720
+ * Emails or user ids. An active member, or a guest who can already open the
721
+ * report — anyone else is refused rather than emailed. You cannot name
722
+ * yourself.
723
+ */
724
+ reviewers: string[];
725
+ /**
726
+ * How many approvals settle it; one when omitted. A single "changes
727
+ * requested" settles it regardless.
728
+ */
729
+ requiredApprovals?: number;
730
+ /** After this the review expires unanswered. ISO 8601. */
731
+ expiresAt?: string;
732
+ /** Your own reference, returned unchanged and searchable. */
733
+ externalId?: string;
734
+ /**
735
+ * The flow this belongs to, when it is one step of a larger piece of work.
736
+ * Must be an open flow in your organisation. `flow.approve()` and its
737
+ * siblings set this for you.
738
+ */
739
+ flowId?: string;
740
+ /**
741
+ * Where to POST the outcome when a person answers, instead of polling:
742
+ * HTTPS, and a public address. The call that makes the request returns the
743
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
744
+ */
745
+ callbackUrl?: string;
746
+ metadata?: Record<string, unknown>;
747
+ }
748
+
749
+ export interface ReviewerRef {
750
+ kind: "user" | "guest";
751
+ id: string;
752
+ label: string;
753
+ }
754
+
755
+ export interface ReviewVerdict {
756
+ verdict: "approved" | "changes_requested";
757
+ /** Who gave it, as a name rather than an id. */
758
+ by: string;
759
+ note: string | null;
760
+ at: string;
761
+ }
762
+
763
+ export interface ReviewData {
764
+ id: string;
765
+ status: ReviewStatus;
766
+ /** The page the reviewer reads and decides on. */
767
+ url: string;
768
+ title: string;
769
+ instructions: string | null;
770
+ reportId: string | null;
771
+ versionId: string | null;
772
+ externalId: string | null;
773
+ metadata: Record<string, unknown>;
774
+ requestedBy: string;
775
+ requiredApprovals: number;
776
+ reviewers: ReviewerRef[];
777
+ verdicts: ReviewVerdict[];
778
+ /** How many comment threads the reviewers opened while reading. */
779
+ threadCount: number;
780
+ settledAt: string | null;
781
+ expiresAt: string | null;
782
+ createdAt: string;
783
+ }
784
+
785
+ /** The answer, flattened — what `review()` hands back. */
786
+ export interface ReviewOutcome {
787
+ /** The one to branch on. False for changes requested, expired and cancelled. */
788
+ approved: boolean;
789
+ status: Exclude<ReviewStatus, "pending">;
790
+ /** Every verdict returned, in the order they arrived. */
791
+ verdicts: ReviewVerdict[];
792
+ /** How many comment threads to read before producing the next version. */
793
+ threadCount: number;
794
+ id: string;
795
+ url: string;
796
+ review: ReviewData;
797
+ }
798
+
799
+ export interface ListReviewsInput {
800
+ status?: ReviewStatus;
801
+ externalId?: string;
802
+ reportId?: string;
803
+ /** One page of this size. Leave it unset to get every row. */
804
+ limit?: number;
805
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
806
+ cursor?: string;
807
+ }
808
+
809
+ /* ── Collections ──────────────────────────────────────────────────────────── */
810
+
811
+ export type CollectionStatus = "pending" | "complete" | "expired" | "cancelled";
812
+
813
+ export type QuestionKind =
814
+ | "text"
815
+ | "long_text"
816
+ | "number"
817
+ | "date"
818
+ | "choice"
819
+ | "multi_choice"
820
+ | "boolean";
821
+
822
+ /** What an answer can hold, shaped by its question's kind. */
823
+ export type AnswerValue = string | number | boolean | string[];
824
+
825
+ export interface QuestionInput {
826
+ /** The question, as you would ask it out loud. */
827
+ prompt: string;
828
+ /** The sentence under the field that stops the wrong answer being given. */
829
+ help?: string;
830
+ kind: QuestionKind;
831
+ /** Required unless you say otherwise; a required question blocks submission. */
832
+ required?: boolean;
833
+ /** For `choice` and `multi_choice`. At least two, or it is not a question. */
834
+ options?: string[];
835
+ }
836
+
837
+ export interface CreateCollectionInput {
838
+ /** What you need, as a headline the person sees first. */
839
+ title: string;
840
+ /** Why you are asking, shown above the questions. */
841
+ instructions?: string;
842
+ questions: QuestionInput[];
843
+ /**
844
+ * Emails or user ids. An active member, or a guest the organisation already
845
+ * knows — anyone else is refused rather than emailed.
846
+ */
847
+ respondents: string[];
848
+ /** How many submitted replies complete it; everyone asked, when omitted. */
849
+ requiredResponses?: number;
850
+ /** A published report the request is about. */
851
+ reportId?: string;
852
+ /** Shown to the person, and what the single reminder is measured against. */
853
+ dueAt?: string;
854
+ /** After this the request closes unanswered. ISO 8601. */
855
+ expiresAt?: string;
856
+ externalId?: string;
857
+ /**
858
+ * The flow this belongs to, when it is one step of a larger piece of work.
859
+ * Must be an open flow in your organisation. `flow.approve()` and its
860
+ * siblings set this for you.
861
+ */
862
+ flowId?: string;
863
+ /**
864
+ * Where to POST the outcome when a person answers, instead of polling:
865
+ * HTTPS, and a public address. The call that makes the request returns the
866
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
867
+ */
868
+ callbackUrl?: string;
869
+ metadata?: Record<string, unknown>;
870
+ }
871
+
872
+ export interface CollectionQuestion {
873
+ id: string;
874
+ prompt: string;
875
+ help: string | null;
876
+ kind: QuestionKind;
877
+ required: boolean;
878
+ options: string[];
879
+ }
880
+
881
+ export interface CollectionReply {
882
+ /** Who answered, as a name rather than an id. */
883
+ respondent: string;
884
+ status: "pending" | "submitted";
885
+ submittedAt: string | null;
886
+ /** Empty until they submit: a half-typed draft is not what they meant to say. */
887
+ answers: { question: string; kind: QuestionKind; value: AnswerValue }[];
888
+ }
889
+
890
+ export interface CollectionData {
891
+ id: string;
892
+ status: CollectionStatus;
893
+ /** The page the person fills in. */
894
+ url: string;
895
+ title: string;
896
+ instructions: string | null;
897
+ reportId: string | null;
898
+ externalId: string | null;
899
+ metadata: Record<string, unknown>;
900
+ requestedBy: string;
901
+ requiredResponses: number;
902
+ questions: CollectionQuestion[];
903
+ responses: CollectionReply[];
904
+ submittedCount: number;
905
+ askedCount: number;
906
+ settledAt: string | null;
907
+ dueAt: string | null;
908
+ expiresAt: string | null;
909
+ createdAt: string;
910
+ }
911
+
912
+ /** The answers, flattened — what `collect()` hands back. */
913
+ export interface CollectedAnswers {
914
+ /** True when enough people replied; false if it expired or was withdrawn. */
915
+ complete: boolean;
916
+ status: Exclude<CollectionStatus, "pending">;
917
+ /** Every submitted reply, in the order they arrived. */
918
+ responses: CollectionReply[];
919
+ /**
920
+ * The first submitted answer to each question, by its prompt — the shape
921
+ * most callers want when they asked one person for three facts.
922
+ */
923
+ answers: Record<string, AnswerValue>;
924
+ id: string;
925
+ url: string;
926
+ collection: CollectionData;
927
+ }
928
+
929
+ export interface ListCollectionsInput {
930
+ status?: CollectionStatus;
931
+ externalId?: string;
932
+ /** One page of this size. Leave it unset to get every row. */
933
+ limit?: number;
934
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
935
+ cursor?: string;
936
+ }
937
+
938
+ /* ── Flows ────────────────────────────────────────────────────────────────── */
939
+
940
+ export type FlowStatus = "open" | "complete" | "cancelled";
941
+ export type FlowMemberKind = "approval" | "review" | "collection" | "report";
942
+
943
+ export interface FlowMember {
944
+ kind: FlowMemberKind;
945
+ id: string;
946
+ title: string;
947
+ /** The member's own status word, which differs by kind. */
948
+ status: string;
949
+ /** Still waiting on somebody. Always false for a report. */
950
+ open: boolean;
951
+ createdAt: string;
952
+ }
953
+
954
+ /** One line of the history: what happened, who did it, when. */
955
+ export interface FlowEvent {
956
+ event: string;
957
+ actor: string;
958
+ actorType: string;
959
+ resourceType: string | null;
960
+ resourceId: string | null;
961
+ at: string;
962
+ }
963
+
964
+ export interface FlowData {
965
+ id: string;
966
+ status: FlowStatus;
967
+ /** The timeline page a person can open. */
968
+ url: string;
969
+ title: string;
970
+ description: string | null;
971
+ externalId: string | null;
972
+ metadata: Record<string, unknown>;
973
+ startedBy: string;
974
+ members: FlowMember[];
975
+ memberCount: number;
976
+ openCount: number;
977
+ /** Nothing outstanding right now — not a claim that the job is finished. */
978
+ allSettled: boolean;
979
+ /** Present on a single read, absent from a list. */
980
+ timeline?: FlowEvent[];
981
+ settledAt: string | null;
982
+ createdAt: string;
983
+ }
984
+
985
+ export interface CreateFlowInput {
986
+ /** What this piece of work is, as the timeline will be titled. */
987
+ title: string;
988
+ /** What it is for, for whoever reads the history a year from now. */
989
+ description?: string;
990
+ workspaceId?: string;
991
+ /** Your own reference. Pass it and use `resume()` so a restart does not start a second flow. */
992
+ externalId?: string;
993
+ metadata?: Record<string, unknown>;
994
+ }
995
+
996
+ export interface ListFlowsInput {
997
+ status?: FlowStatus;
998
+ externalId?: string;
999
+ /** One page of this size. Leave it unset to get every row. */
1000
+ limit?: number;
1001
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
1002
+ cursor?: string;
1003
+ }
1004
+
1005
+ /* ── Tasks ────────────────────────────────────────────────────────────────── */
1006
+
1007
+ /*
1008
+ * Task Graph: an objective kept apart from the conversation doing the work,
1009
+ * the side tasks branched out of it, and the findings each one produced.
1010
+ *
1011
+ * Every nested shape is named rather than written inline, so the Python SDK
1012
+ * can carry the same class under the same name and the parity guard can hold
1013
+ * the two to each other field by field.
1014
+ */
1015
+
1016
+ export type TaskKind = "objective" | "side_task" | "investigation" | "research" | "debug" | "decision";
1017
+ export type SideTaskKind = "side_task" | "investigation" | "research" | "debug" | "decision";
1018
+ export type TaskStatus = "open" | "in_progress" | "blocked" | "awaiting_approval" | "completed" | "cancelled";
1019
+ /** The statuses `update()` may set. Completing and cancelling have their own calls. */
1020
+ export type SettableTaskStatus = "open" | "in_progress" | "blocked" | "awaiting_approval";
1021
+ /** What became of a finished side task's result: carried into the parent, kept for reference, or not used. */
1022
+ export type TaskOutcome = "applied" | "kept" | "discarded";
1023
+ export type FindingKind =
1024
+ | "hypothesis"
1025
+ | "test"
1026
+ | "evidence"
1027
+ | "finding"
1028
+ | "conclusion"
1029
+ | "recommendation"
1030
+ | "decision"
1031
+ | "risk"
1032
+ | "question"
1033
+ | "action";
1034
+ /** A decision is a suggestion until a person confirms it. */
1035
+ export type DecisionStatus = "suggested" | "confirmed" | "rejected";
1036
+ export type TaskLinkKind = "depends_on" | "blocks" | "related_to" | "supersedes" | "resulted_in";
1037
+
1038
+ /** The short working state of a task: where it stands, what is open, what is in the way, what comes next. */
1039
+ export interface TaskState {
1040
+ currentState: string | null;
1041
+ openQuestions: string[];
1042
+ constraints: string[];
1043
+ blockedBy: string[];
1044
+ nextAction: string | null;
1045
+ }
1046
+
1047
+ /**
1048
+ * A change to a task's state. Fields left out stay as they were; a list sent
1049
+ * replaces the list; `addOpenQuestions` and `resolveOpenQuestions` change it
1050
+ * item by item, so two writers do not have to agree on the whole list.
1051
+ */
1052
+ export interface TaskStatePatch {
1053
+ currentState?: string | null;
1054
+ openQuestions?: string[];
1055
+ addOpenQuestions?: string[];
1056
+ resolveOpenQuestions?: string[];
1057
+ constraints?: string[];
1058
+ blockedBy?: string[];
1059
+ nextAction?: string | null;
1060
+ }
1061
+
1062
+ /** What a side task was given when it began. Not a transcript: the facts it needs. */
1063
+ export interface TaskSnapshot {
1064
+ rootObjective: string;
1065
+ parentObjective: string;
1066
+ sideTaskGoal: string;
1067
+ relevantContext: string[];
1068
+ knownConstraints: string[];
1069
+ relatedDecisions: string[];
1070
+ /** The parent's open question this side task was opened to answer, if any. */
1071
+ resolvesQuestion: string | null;
1072
+ }
1073
+
1074
+ export interface TaskResultFinding {
1075
+ title: string;
1076
+ description: string;
1077
+ evidence?: string[];
1078
+ }
1079
+
1080
+ export interface TaskResultDecision {
1081
+ title: string;
1082
+ rationale?: string;
1083
+ }
1084
+
1085
+ /** What a side task came back with. Structured, so the parent can use it. */
1086
+ export interface TaskResult {
1087
+ summary: string;
1088
+ findings: TaskResultFinding[];
1089
+ decisions: TaskResultDecision[];
1090
+ recommendations: string[];
1091
+ unresolvedQuestions: string[];
1092
+ parentImpact: string | null;
1093
+ suggestedNextAction: string | null;
1094
+ }
1095
+
1096
+ /** An objective's side tasks, counted. On a list only. */
1097
+ export interface SideTaskCounts {
1098
+ open: number;
1099
+ done: number;
1100
+ /** Finished and waiting for somebody to apply, keep or discard the result. */
1101
+ awaiting: number;
1102
+ }
1103
+
1104
+ /** One step from the objective down to a task. */
1105
+ export interface TaskPathEntry {
1106
+ id: string;
1107
+ title: string;
1108
+ kind: TaskKind;
1109
+ }
1110
+
1111
+ export interface TaskLink {
1112
+ sourceTaskId: string;
1113
+ targetTaskId: string;
1114
+ kind: TaskLinkKind;
1115
+ }
1116
+
1117
+ /** A task as the tree shows it: no state, no snapshot, one line of the result. */
1118
+ export interface TaskNode {
1119
+ id: string;
1120
+ parentTaskId: string | null;
1121
+ kind: TaskKind;
1122
+ depth: number;
1123
+ status: TaskStatus;
1124
+ title: string;
1125
+ outcome: TaskOutcome | null;
1126
+ resultSummary: string | null;
1127
+ url: string;
1128
+ }
1129
+
1130
+ /** An inspectable work product: what was tested, seen or concluded. Never private reasoning. */
1131
+ export interface TaskFinding {
1132
+ id: string;
1133
+ taskId: string;
1134
+ kind: FindingKind;
1135
+ title: string;
1136
+ body: string;
1137
+ evidence: string[];
1138
+ /** For a decision: suggested, confirmed or rejected, with any approval taken into account. */
1139
+ decisionStatus: DecisionStatus | null;
1140
+ decidedBy: string | null;
1141
+ decidedAt: string | null;
1142
+ approvalId: string | null;
1143
+ /** The approval's own status, when a decision was put to one. */
1144
+ approvalStatus: string | null;
1145
+ /** The side task it came from, when it arrived with an applied result. */
1146
+ sourceTaskId: string | null;
1147
+ createdBy: string;
1148
+ createdAt: string;
1149
+ }
1150
+
1151
+ export interface TaskData {
1152
+ id: string;
1153
+ kind: TaskKind;
1154
+ status: TaskStatus;
1155
+ /** The page a person can open. */
1156
+ url: string;
1157
+ title: string;
1158
+ /** What the work is for: the objective's purpose, or a side task's goal. */
1159
+ objective: string;
1160
+ rootTaskId: string;
1161
+ /** Null on the objective itself. */
1162
+ parentTaskId: string | null;
1163
+ depth: number;
1164
+ workspaceId: string | null;
1165
+ flowId: string | null;
1166
+ state: TaskState;
1167
+ /** For a side task: what it was given when it began. */
1168
+ snapshot: TaskSnapshot | null;
1169
+ /** Once completed: what it came back with. */
1170
+ result: TaskResult | null;
1171
+ /** Earlier results, kept when a completed task is reopened. */
1172
+ previousResults: TaskResult[];
1173
+ outcome: TaskOutcome | null;
1174
+ origin: "manual" | "suggested";
1175
+ externalId: string | null;
1176
+ sessionUrl: string | null;
1177
+ /** Pass it back as `expectedVersion` to refuse an update somebody else got in before. */
1178
+ version: number;
1179
+ startedBy: string;
1180
+ createdAt: string;
1181
+ updatedAt: string;
1182
+ completedAt: string | null;
1183
+ /** On a list only. */
1184
+ sideTasks?: SideTaskCounts;
1185
+ /** On a single read: from the objective down to this task. */
1186
+ path?: TaskPathEntry[];
1187
+ /** On a single read: the side tasks directly under this one. */
1188
+ children?: TaskNode[];
1189
+ /** On a single read. */
1190
+ findings?: TaskFinding[];
1191
+ /** On a single read. */
1192
+ links?: TaskLink[];
1193
+ /** On create only: true when an open objective with this `externalId` was returned instead of a new one. */
1194
+ resumed?: boolean;
1195
+ }
1196
+
1197
+ export interface TaskContextTask {
1198
+ id: string;
1199
+ kind: TaskKind;
1200
+ title: string;
1201
+ objective: string;
1202
+ status: TaskStatus;
1203
+ isSideTask: boolean;
1204
+ }
1205
+
1206
+ export interface TaskContextDecisions {
1207
+ confirmed: string[];
1208
+ suggested: string[];
1209
+ }
1210
+
1211
+ export interface TaskContextFinding {
1212
+ kind: FindingKind;
1213
+ title: string;
1214
+ body: string;
1215
+ }
1216
+
1217
+ export interface ActiveSideTask {
1218
+ id: string;
1219
+ title: string;
1220
+ kind: TaskKind;
1221
+ status: TaskStatus;
1222
+ }
1223
+
1224
+ /** Finished, and waiting for somebody to apply, keep or discard the result. */
1225
+ export interface AwaitingSideTask {
1226
+ id: string;
1227
+ title: string;
1228
+ summary: string | null;
1229
+ }
1230
+
1231
+ export interface CompletedSideTask {
1232
+ id: string;
1233
+ title: string;
1234
+ summary: string | null;
1235
+ outcome: TaskOutcome | null;
1236
+ }
1237
+
1238
+ export interface TaskContextSideTasks {
1239
+ active: ActiveSideTask[];
1240
+ awaitingOutcome: AwaitingSideTask[];
1241
+ completed: CompletedSideTask[];
1242
+ }
1243
+
1244
+ /**
1245
+ * What an agent reads instead of the history: the objective first, always,
1246
+ * then where this task stands and what is settled. Small on purpose.
1247
+ */
1248
+ export interface TaskContext {
1249
+ rootObjective: string;
1250
+ task: TaskContextTask;
1251
+ path: TaskPathEntry[];
1252
+ currentState: string | null;
1253
+ nextAction: string | null;
1254
+ openQuestions: string[];
1255
+ constraints: string[];
1256
+ blockedBy: string[];
1257
+ decisions: TaskContextDecisions;
1258
+ snapshot: TaskSnapshot | null;
1259
+ relevantFindings: TaskContextFinding[];
1260
+ sideTasks: TaskContextSideTasks;
1261
+ /** One paragraph to say back to yourself to re-anchor on the objective. */
1262
+ reanchor: string;
1263
+ }
1264
+
1265
+ export interface TaskGraph {
1266
+ root: TaskData;
1267
+ nodes: TaskNode[];
1268
+ links: TaskLink[];
1269
+ }
1270
+
1271
+ /** What applying a side task's result did: both tasks as they now are, and the parent's fresh context. */
1272
+ export interface AppliedSideTask {
1273
+ sideTask: TaskData;
1274
+ parent: TaskData;
1275
+ message: string;
1276
+ context: TaskContext;
1277
+ }
1278
+
1279
+ export interface DecisionApproval {
1280
+ finding: TaskFinding;
1281
+ approvalId: string;
1282
+ approvalUrl: string;
1283
+ }
1284
+
1285
+ export interface TaskLinkResult {
1286
+ linked: boolean;
1287
+ sourceTaskId: string;
1288
+ targetTaskId: string;
1289
+ kind: TaskLinkKind;
1290
+ /** False when the link already existed. */
1291
+ created: boolean;
1292
+ }
1293
+
1294
+ export interface CreateTaskInput {
1295
+ /** A short name for the objective. */
1296
+ title: string;
1297
+ /** What the work is ultimately for. Returned at the top of every context. */
1298
+ objective: string;
1299
+ workspaceId?: string;
1300
+ /** The flow its approvals and reviews belong to. */
1301
+ flowId?: string;
1302
+ /** Your own reference. An open objective you started under it is returned instead of a new one. */
1303
+ externalId?: string;
1304
+ /** A link to the conversation where the work happens. */
1305
+ sessionUrl?: string;
1306
+ /** The starting state, if anything is already known. */
1307
+ state?: TaskStatePatch;
1308
+ /**
1309
+ * Govern it from the start (Compliance Mode, Business and Enterprise): the
1310
+ * AI system, purpose, owners, risk, data and oversight. Refused on a plan
1311
+ * without Compliance Mode.
1312
+ */
1313
+ governance?: GovernanceProfileInput;
1314
+ }
1315
+
1316
+ /** A governed task's profile, as far as it is known. Every field is optional. */
1317
+ export interface GovernanceProfileInput {
1318
+ aiSystemId?: string | null;
1319
+ purpose?: string | null;
1320
+ businessOwner?: string | null;
1321
+ technicalOwner?: string | null;
1322
+ risk?: "low" | "medium" | "high" | "critical";
1323
+ dataClassification?: "public" | "internal" | "confidential" | "restricted" | null;
1324
+ personalData?: boolean;
1325
+ sensitiveData?: boolean;
1326
+ customerFacing?: boolean;
1327
+ productionUse?: boolean;
1328
+ autonomy?: "assist" | "recommend" | "act_with_approval" | "act_autonomously" | null;
1329
+ decisionImpact?: "none" | "informs" | "supports_decision" | "automated_decision" | null;
1330
+ oversight?:
1331
+ | "none"
1332
+ | "post_action_review"
1333
+ | "sampled_review"
1334
+ | "human_on_the_loop"
1335
+ | "human_in_the_loop"
1336
+ | "pre_action_approval"
1337
+ | "dual_approval"
1338
+ | null;
1339
+ jurisdictions?: string[];
1340
+ }
1341
+
1342
+ export interface ListTasksInput {
1343
+ /** A status, or `active` for anything not completed or cancelled. */
1344
+ status?: TaskStatus | "active";
1345
+ externalId?: string;
1346
+ /** Search the titles and objectives. */
1347
+ q?: string;
1348
+ /** One page of this size. Leave it unset to get every row. */
1349
+ limit?: number;
1350
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
1351
+ cursor?: string;
1352
+ }
1353
+
1354
+ export interface UpdateTaskInput {
1355
+ title?: string;
1356
+ /** Refused to an agent: only a person changes what the work is for. Propose it as a finding. */
1357
+ objective?: string;
1358
+ status?: SettableTaskStatus;
1359
+ sessionUrl?: string | null;
1360
+ state?: TaskStatePatch;
1361
+ /** The version you read; the update is refused if somebody wrote in between. */
1362
+ expectedVersion?: number;
1363
+ }
1364
+
1365
+ export interface CreateSideTaskInput {
1366
+ title: string;
1367
+ /** What exactly it has to solve. Narrow is better: it is done when this is answered. */
1368
+ goal: string;
1369
+ kind?: SideTaskKind;
1370
+ /** The context it needs, replacing what Deliverd would select from the parent. */
1371
+ relevantContext?: string[];
1372
+ /** What it must respect; the parent's constraints when omitted. */
1373
+ knownConstraints?: string[];
1374
+ /** One of the parent's open questions; it comes off the list when the result is applied. */
1375
+ resolvesQuestion?: string;
1376
+ /** `suggested` when you proposed the side task and the person agreed. */
1377
+ origin?: "manual" | "suggested";
1378
+ sessionUrl?: string;
1379
+ }
1380
+
1381
+ export interface AddFindingInput {
1382
+ /** A `decision` is recorded as a suggestion until a person confirms it. */
1383
+ kind: FindingKind;
1384
+ title: string;
1385
+ /** The substance, written for a person: what you tested, saw or concluded. */
1386
+ body?: string;
1387
+ /** Short pieces of evidence: a log line, a value, a measurement. */
1388
+ evidence?: string[];
1389
+ }
1390
+
1391
+ export interface CompleteTaskInput {
1392
+ /** What was found, in a few sentences. */
1393
+ summary: string;
1394
+ findings?: TaskResultFinding[];
1395
+ /** Decisions you propose. They reach the parent as suggestions. */
1396
+ decisions?: TaskResultDecision[];
1397
+ recommendations?: string[];
1398
+ /** Added to the parent's open questions when applied. */
1399
+ unresolvedQuestions?: string[];
1400
+ /** What this means for the main task. */
1401
+ parentImpact?: string;
1402
+ /** Becomes the parent's next action when applied. */
1403
+ suggestedNextAction?: string;
1404
+ }
1405
+
1406
+ export interface ApplySideTaskInput {
1407
+ /** `applied` (the default) carries the result into the parent; `kept` records it as reference; `discarded` records it was not used. */
1408
+ outcome?: TaskOutcome;
1409
+ }
1410
+
1411
+ export interface CancelTaskInput {
1412
+ /** Why it was called off, for whoever reads the history. */
1413
+ reason?: string;
1414
+ }
1415
+
1416
+ export interface RequestDecisionApprovalInput {
1417
+ /** Emails, names or groups; the organisation's administrators when omitted. */
1418
+ approvers?: string[];
1419
+ note?: string;
1420
+ expiresAt?: string;
1421
+ }
1422
+
1423
+ export interface LinkTasksInput {
1424
+ targetTaskId: string;
1425
+ kind: TaskLinkKind;
1426
+ }
1427
+
1428
+ /* ── Evidence ─────────────────────────────────────────────────────────────── */
1429
+
1430
+ export type EvidenceStepKind = "approval" | "review" | "collection" | "report";
1431
+
1432
+ export interface EvidenceOutcome {
1433
+ who: string;
1434
+ /** What they said, in the words the step uses: "approved", "answered". */
1435
+ said: string;
1436
+ note: string | null;
1437
+ at: string;
1438
+ }
1439
+
1440
+ export interface EvidenceStep {
1441
+ kind: EvidenceStepKind;
1442
+ id: string;
1443
+ title: string;
1444
+ status: string;
1445
+ url: string;
1446
+ createdAt: string;
1447
+ settledAt: string | null;
1448
+ requestedBy: string;
1449
+ /** Whether an agent asked for this, which is the point of the record. */
1450
+ requestedByAgent: boolean;
1451
+ asked: string[];
1452
+ outcomes: EvidenceOutcome[];
1453
+ /** Whatever else the step records: the description, the questions, the answers. */
1454
+ detail: Record<string, unknown>;
1455
+ }
1456
+
1457
+ export interface EvidenceEvent {
1458
+ at: string;
1459
+ event: string;
1460
+ actor: string;
1461
+ actorType: string;
1462
+ /** Which step it happened to, when it happened to one. */
1463
+ step: string | null;
1464
+ metadata: Record<string, unknown>;
1465
+ }
1466
+
1467
+ export interface EvidencePack {
1468
+ packVersion: number;
1469
+ generatedAt: string;
1470
+ generatedBy: string;
1471
+ organisation: { id: string; name: string };
1472
+ subject: {
1473
+ kind: "flow" | "report";
1474
+ id: string;
1475
+ title: string;
1476
+ url: string;
1477
+ status: string;
1478
+ startedBy: string;
1479
+ startedAt: string;
1480
+ };
1481
+ summary: {
1482
+ steps: number;
1483
+ events: number;
1484
+ firstEventAt: string | null;
1485
+ lastEventAt: string | null;
1486
+ };
1487
+ steps: EvidenceStep[];
1488
+ timeline: EvidenceEvent[];
1489
+ /**
1490
+ * What the digest does and does not stand for, in the pack's own words.
1491
+ *
1492
+ * `covers` says it detects a file altered after export. `doesNotCover` says
1493
+ * it makes no claim about the database. Both travel with the pack rather
1494
+ * than living only in documentation, because a reader who sees a hash and
1495
+ * no sentence will assume the stronger one.
1496
+ */
1497
+ integrity: {
1498
+ algorithm: "sha256";
1499
+ digest: string;
1500
+ covers: string;
1501
+ doesNotCover: string;
1502
+ recordsAreInsertOnly: boolean;
1503
+ };
1504
+ }
1505
+
1506
+ /**
1507
+ * What arrives at a request's `callbackUrl`.
1508
+ *
1509
+ * `data` is the same object an organisation webhook carries for the event.
1510
+ * `approval.question` means the approver asked something and is waiting on
1511
+ * your answer (`answerQuestion`); every other event is the request settling.
1512
+ */
1513
+ export interface CallbackEnvelope {
1514
+ event:
1515
+ | "approval.approved"
1516
+ | "approval.rejected"
1517
+ | "approval.changes_requested"
1518
+ | "approval.expired"
1519
+ | "approval.question"
1520
+ | "review.approved"
1521
+ | "review.changes_requested"
1522
+ | "review.expired"
1523
+ | "collection.completed"
1524
+ | "collection.expired"
1525
+ | "gate.approved"
1526
+ | "gate.rejected"
1527
+ | "gate.changes_requested"
1528
+ | "gate.expired"
1529
+ | "gate.cancelled"
1530
+ | "gate.revoked"
1531
+ | "gate.executed";
1532
+ sentAt: string;
1533
+ requestType: "approval" | "review" | "collection" | "gate";
1534
+ requestId: string;
1535
+ data: Record<string, unknown>;
1536
+ }