@deliverd/sdk 0.8.1 → 0.8.2
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/LICENSE +21 -21
- package/README.md +562 -562
- package/dist/messages.d.ts.map +1 -1
- package/dist/messages.js +84 -5
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +413 -0
- package/package.json +55 -55
- package/src/approvals.ts +322 -322
- package/src/collections.ts +236 -236
- package/src/dev.ts +761 -761
- package/src/duration.ts +21 -21
- package/src/errors.ts +62 -62
- package/src/flows.ts +222 -222
- package/src/gates.ts +230 -230
- package/src/http.ts +217 -217
- package/src/index.ts +443 -443
- package/src/messages.ts +161 -82
- package/src/paging.ts +64 -64
- package/src/released.ts +2072 -1658
- package/src/reports.ts +490 -490
- package/src/reviews.ts +225 -225
- package/src/types.ts +838 -838
- package/src/webhooks.ts +98 -98
package/src/types.ts
CHANGED
|
@@ -1,838 +1,838 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The API's objects, by hand.
|
|
3
|
-
*
|
|
4
|
-
* Not imported from the server's zod schemas on purpose: this package is
|
|
5
|
-
* published to npm and must not drag the monorepo's internals with it. The
|
|
6
|
-
* cost of that is drift, so `apps/web/src/lib/services/api-approvals.test.ts`
|
|
7
|
-
* holds these shapes to the schemas the API actually validates — a field added
|
|
8
|
-
* there and not here fails the build on the server side, where someone is
|
|
9
|
-
* looking.
|
|
10
|
-
*/
|
|
11
|
-
|
|
12
|
-
export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled";
|
|
13
|
-
export type ApprovalRisk = "low" | "medium" | "high" | "critical";
|
|
14
|
-
|
|
15
|
-
/**
|
|
16
|
-
* What a gate decision can be.
|
|
17
|
-
*
|
|
18
|
-
* Seven, and the extra four over `allowed | denied | pending` are worth the
|
|
19
|
-
* width. `allowed` and `denied` are what a *rule* said; the rest are what a
|
|
20
|
-
* *person* did about a request no rule settled. An action that went through
|
|
21
|
-
* because policy permitted it and one that went through because somebody
|
|
22
|
-
* agreed to it are not the same fact — the ratio between them is the number
|
|
23
|
-
* this whole layer exists to make computable — so collapsing them would throw
|
|
24
|
-
* away the distinction at the one place a caller can see it.
|
|
25
|
-
*/
|
|
26
|
-
export type GateStatus =
|
|
27
|
-
| "allowed"
|
|
28
|
-
| "denied"
|
|
29
|
-
| "pending"
|
|
30
|
-
| "approved"
|
|
31
|
-
| "rejected"
|
|
32
|
-
| "expired"
|
|
33
|
-
| "cancelled";
|
|
34
|
-
|
|
35
|
-
/** What a person decided about a gate, once one has. */
|
|
36
|
-
export type GateOutcomeName = "approved" | "rejected" | "cancelled" | "expired";
|
|
37
|
-
|
|
38
|
-
export interface CreateGateInput {
|
|
39
|
-
/** The registered action you are about to perform: `finance.refund`. */
|
|
40
|
-
actionId: string;
|
|
41
|
-
/** The arguments you will actually execute with. Validated against the action's schema. */
|
|
42
|
-
input: Record<string, unknown>;
|
|
43
|
-
/**
|
|
44
|
-
* Your id for this unit of work — `refund:ord_8812`. **Required**, which no
|
|
45
|
-
* other create in this SDK is.
|
|
46
|
-
*
|
|
47
|
-
* Every other POST mints a random idempotency key per attempt, which guards a
|
|
48
|
-
* retried *request*. This guards a retried *decision*: a crashed agent that
|
|
49
|
-
* re-runs its refund step must re-read the answer it already got, not ask a
|
|
50
|
-
* second person about the same money. No id the SDK invented could know which
|
|
51
|
-
* two calls are the same attempt, so you name it.
|
|
52
|
-
*/
|
|
53
|
-
externalId: string;
|
|
54
|
-
/** Where this is running, for rules that tell staging from production. */
|
|
55
|
-
environment?: string;
|
|
56
|
-
/** Why, shown to whoever is asked to decide. */
|
|
57
|
-
reason?: string;
|
|
58
|
-
flowId?: string;
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
export interface GateData {
|
|
62
|
-
id: string;
|
|
63
|
-
status: GateStatus;
|
|
64
|
-
/** The one to branch on: a rule permitted it, or a person agreed to it. */
|
|
65
|
-
allowed: boolean;
|
|
66
|
-
/** The input as the action's schema validated it — what to execute with. */
|
|
67
|
-
input: Record<string, unknown>;
|
|
68
|
-
/** Whether a rule decided this or a person did. */
|
|
69
|
-
basis: "policy" | "human";
|
|
70
|
-
reason: string | null;
|
|
71
|
-
/** The rule that decided, by name. Null when nothing matched. */
|
|
72
|
-
rule: string | null;
|
|
73
|
-
policyVersionId: string | null;
|
|
74
|
-
approvalId: string | null;
|
|
75
|
-
approvalUrl: string | null;
|
|
76
|
-
outcome: GateOutcomeName | null;
|
|
77
|
-
settledAt: string | null;
|
|
78
|
-
/** True when this call found a decision already made under your `externalId`. */
|
|
79
|
-
reused: boolean;
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
/**
|
|
83
|
-
* The answer, flattened — what `gate()` hands back.
|
|
84
|
-
*
|
|
85
|
-
* `allowed` is a boolean so `if (decision.allowed)` reads as the sentence it
|
|
86
|
-
* is; `status` is the narrowing union for a switch. The same pairing, for the
|
|
87
|
-
* same reason, as `Decision` on an approval.
|
|
88
|
-
*/
|
|
89
|
-
export interface GateDecision {
|
|
90
|
-
allowed: boolean;
|
|
91
|
-
status: GateStatus;
|
|
92
|
-
reason: string | null;
|
|
93
|
-
rule: string | null;
|
|
94
|
-
input: Record<string, unknown>;
|
|
95
|
-
id: string;
|
|
96
|
-
approvalUrl: string | null;
|
|
97
|
-
gate: unknown;
|
|
98
|
-
}
|
|
99
|
-
|
|
100
|
-
/** One line of evidence, as the approval page shows it. */
|
|
101
|
-
export interface ApprovalFactor {
|
|
102
|
-
label: string;
|
|
103
|
-
status?: "ok" | "warning" | "info";
|
|
104
|
-
detail?: string;
|
|
105
|
-
}
|
|
106
|
-
|
|
107
|
-
export interface ApprovalLink {
|
|
108
|
-
label: string;
|
|
109
|
-
url: string;
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
export interface ApprovalQuestion {
|
|
113
|
-
id: string;
|
|
114
|
-
question: string;
|
|
115
|
-
answer: string | null;
|
|
116
|
-
askedAt: string;
|
|
117
|
-
answeredAt: string | null;
|
|
118
|
-
}
|
|
119
|
-
|
|
120
|
-
export interface ApprovalData {
|
|
121
|
-
id: string;
|
|
122
|
-
status: ApprovalStatus;
|
|
123
|
-
/** The page the approver decides on. */
|
|
124
|
-
url: string;
|
|
125
|
-
title: string;
|
|
126
|
-
description: string | null;
|
|
127
|
-
risk: ApprovalRisk;
|
|
128
|
-
factors: ApprovalFactor[];
|
|
129
|
-
links: ApprovalLink[];
|
|
130
|
-
reportId: string | null;
|
|
131
|
-
externalId: string | null;
|
|
132
|
-
metadata: Record<string, unknown>;
|
|
133
|
-
requestedBy: string;
|
|
134
|
-
approvers: string[];
|
|
135
|
-
/**
|
|
136
|
-
* How many people must agree before it settles. One unless a standing rule
|
|
137
|
-
* in the organisation escalated it — an agent cannot set this, and a rule
|
|
138
|
-
* can only push it up.
|
|
139
|
-
*/
|
|
140
|
-
requiredApprovals: number;
|
|
141
|
-
/** How many have approved so far. Compare with `requiredApprovals`. */
|
|
142
|
-
approvalsSoFar: number;
|
|
143
|
-
/** Who decided, as a name rather than an id — the same as a review's `by`. */
|
|
144
|
-
decidedBy: string | null;
|
|
145
|
-
/** Their user id, for anything that needs the key rather than the person. */
|
|
146
|
-
decidedById: string | null;
|
|
147
|
-
decidedAt: string | null;
|
|
148
|
-
/** The approver's reason, on a rejection or an approval that carried one. */
|
|
149
|
-
note: string | null;
|
|
150
|
-
expiresAt: string | null;
|
|
151
|
-
questions: ApprovalQuestion[];
|
|
152
|
-
createdAt: string;
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
export interface CreateApprovalInput {
|
|
156
|
-
/** What is being asked, as a headline. */
|
|
157
|
-
title: string;
|
|
158
|
-
/** Why, what it affects, what it costs — what the approver reads first. */
|
|
159
|
-
description?: string;
|
|
160
|
-
/** How the approver should weigh it. Medium when omitted. */
|
|
161
|
-
risk?: ApprovalRisk;
|
|
162
|
-
/** Evidence, one line each, shown as a checklist. */
|
|
163
|
-
factors?: ApprovalFactor[];
|
|
164
|
-
/** Where to read more. */
|
|
165
|
-
links?: ApprovalLink[];
|
|
166
|
-
/** A published report the request is about. */
|
|
167
|
-
reportId?: string;
|
|
168
|
-
/**
|
|
169
|
-
* Who may decide. Each entry is a person — an email or a user id — or the
|
|
170
|
-
* name of a directory group or workspace, or a word meaning the whole
|
|
171
|
-
* organisation ("everyone"). Naming a team is usually what you want: a
|
|
172
|
-
* request addressed to one person waits for that person to come back from
|
|
173
|
-
* holiday, and anyone on a team can answer.
|
|
174
|
-
*
|
|
175
|
-
* The organisation's owners and admins decide when this is omitted. You
|
|
176
|
-
* cannot name only yourself; being *on* a team you address is fine and means
|
|
177
|
-
* the rest of it. A name matching both a person and a team is refused rather
|
|
178
|
-
* than guessed — name it by id.
|
|
179
|
-
*/
|
|
180
|
-
approvers?: string[];
|
|
181
|
-
/** After this the request expires undecided. ISO 8601. */
|
|
182
|
-
expiresAt?: string;
|
|
183
|
-
/** Your own reference, returned unchanged and searchable. */
|
|
184
|
-
externalId?: string;
|
|
185
|
-
/**
|
|
186
|
-
* The flow this belongs to, when it is one step of a larger piece of work.
|
|
187
|
-
* Must be an open flow in your organisation. `flow.approve()` and its
|
|
188
|
-
* siblings set this for you.
|
|
189
|
-
*/
|
|
190
|
-
flowId?: string;
|
|
191
|
-
metadata?: Record<string, unknown>;
|
|
192
|
-
}
|
|
193
|
-
|
|
194
|
-
/**
|
|
195
|
-
* The answer to `approve()`.
|
|
196
|
-
*
|
|
197
|
-
* Flat on purpose: the line after the call is `if (decision.approved)`, and
|
|
198
|
-
* anything a caller has to reach through to get there is a step this SDK
|
|
199
|
-
* exists to remove. The whole request is on `approval` when a field here does
|
|
200
|
-
* not cover it.
|
|
201
|
-
*/
|
|
202
|
-
export type Decision = {
|
|
203
|
-
/** True only for an approval. False for rejected, expired and cancelled. */
|
|
204
|
-
approved: boolean;
|
|
205
|
-
/** For a switch, and for narrowing. */
|
|
206
|
-
status: "approved" | "rejected" | "expired" | "cancelled";
|
|
207
|
-
/** Their reason, when they gave one. */
|
|
208
|
-
note: string | null;
|
|
209
|
-
/** Who decided, as a name rather than an id. Log it; put it in a message. */
|
|
210
|
-
decidedBy: string | null;
|
|
211
|
-
/** Their user id, when the key is what you need. */
|
|
212
|
-
decidedById: string | null;
|
|
213
|
-
decidedAt: string | null;
|
|
214
|
-
id: string;
|
|
215
|
-
/** The page they decided on. Worth logging. */
|
|
216
|
-
url: string;
|
|
217
|
-
/** The request itself, for anything the fields above do not name. */
|
|
218
|
-
approval: unknown;
|
|
219
|
-
};
|
|
220
|
-
|
|
221
|
-
export interface ListApprovalsInput {
|
|
222
|
-
status?: ApprovalStatus;
|
|
223
|
-
externalId?: string;
|
|
224
|
-
/** One page of this size. Leave it unset to get every row. */
|
|
225
|
-
limit?: number;
|
|
226
|
-
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
227
|
-
cursor?: string;
|
|
228
|
-
}
|
|
229
|
-
|
|
230
|
-
/* ── Reports ─────────────────────────────────────────────────────────────── */
|
|
231
|
-
|
|
232
|
-
export interface InlineFile {
|
|
233
|
-
path: string;
|
|
234
|
-
content: string;
|
|
235
|
-
/** `base64` for an image or a font; text otherwise. */
|
|
236
|
-
encoding?: "utf8" | "base64";
|
|
237
|
-
}
|
|
238
|
-
|
|
239
|
-
export interface PublishReportInput {
|
|
240
|
-
title?: string;
|
|
241
|
-
slug?: string;
|
|
242
|
-
description?: string;
|
|
243
|
-
workspaceId?: string;
|
|
244
|
-
/** Names, teams, groups or emails — resolved server-side. */
|
|
245
|
-
audience?: unknown;
|
|
246
|
-
classification?: string;
|
|
247
|
-
living?: boolean;
|
|
248
|
-
sourceTool?: string;
|
|
249
|
-
sourceModel?: string;
|
|
250
|
-
changeSummary?: string;
|
|
251
|
-
/** Publish only if this is still the current version; 0 claims a new slug. */
|
|
252
|
-
expectedVersion?: number;
|
|
253
|
-
uploadId?: string;
|
|
254
|
-
content?: string;
|
|
255
|
-
files?: InlineFile[];
|
|
256
|
-
}
|
|
257
|
-
|
|
258
|
-
export type UpdateReportInput = Pick<
|
|
259
|
-
PublishReportInput,
|
|
260
|
-
| "uploadId"
|
|
261
|
-
| "content"
|
|
262
|
-
| "files"
|
|
263
|
-
| "title"
|
|
264
|
-
| "description"
|
|
265
|
-
| "sourceTool"
|
|
266
|
-
| "sourceModel"
|
|
267
|
-
| "changeSummary"
|
|
268
|
-
| "expectedVersion"
|
|
269
|
-
>;
|
|
270
|
-
|
|
271
|
-
export interface ReportData {
|
|
272
|
-
id: string;
|
|
273
|
-
slug: string;
|
|
274
|
-
title: string;
|
|
275
|
-
url: string;
|
|
276
|
-
status: string;
|
|
277
|
-
currentVersion: number | null;
|
|
278
|
-
[key: string]: unknown;
|
|
279
|
-
}
|
|
280
|
-
|
|
281
|
-
/**
|
|
282
|
-
* A publish held by a policy rule answers 202 with this instead of going live.
|
|
283
|
-
* `status` says which happened, so a caller that ignores it still gets a
|
|
284
|
-
* report object and a caller that reads it knows nobody can see the thing yet.
|
|
285
|
-
*/
|
|
286
|
-
export interface PublishResult {
|
|
287
|
-
status?: "published" | "updated" | "pending_approval";
|
|
288
|
-
report: ReportData;
|
|
289
|
-
version?: { id: string; versionNumber: number; [key: string]: unknown };
|
|
290
|
-
approval?: { id: string; status: string };
|
|
291
|
-
warnings?: string[];
|
|
292
|
-
[key: string]: unknown;
|
|
293
|
-
}
|
|
294
|
-
|
|
295
|
-
/**
|
|
296
|
-
* One open thread, as the organisation-wide list returns it.
|
|
297
|
-
*
|
|
298
|
-
* Deliberately thinner than a `CommentThread`: this answers "where is the
|
|
299
|
-
* feedback" across every report, so it carries the report and the quoted
|
|
300
|
-
* passage rather than the whole conversation. Fetch the thread itself with
|
|
301
|
-
* `comments.list(reportId)` once you know which report to look at.
|
|
302
|
-
*/
|
|
303
|
-
export interface OpenThread {
|
|
304
|
-
threadId: string;
|
|
305
|
-
reportId: string;
|
|
306
|
-
reportTitle: string;
|
|
307
|
-
reportSlug: string;
|
|
308
|
-
/** Who owns the report — filter on it to find the threads on yours. */
|
|
309
|
-
reportOwnerId: string | null;
|
|
310
|
-
quote: string | null;
|
|
311
|
-
author: string;
|
|
312
|
-
authorType: string;
|
|
313
|
-
messages: number;
|
|
314
|
-
lastActivityAt: string;
|
|
315
|
-
}
|
|
316
|
-
|
|
317
|
-
/**
|
|
318
|
-
* What a send did, per address.
|
|
319
|
-
*
|
|
320
|
-
* `delivered` is the mail provider accepting it, not the person reading it —
|
|
321
|
-
* and `alreadyHadAccess` names the recipients who could already open the
|
|
322
|
-
* report, who were emailed again anyway. Re-sending to somebody who says
|
|
323
|
-
* they never got the first one is the point.
|
|
324
|
-
*/
|
|
325
|
-
export interface SendResult {
|
|
326
|
-
sent: { email: string; delivered: boolean }[];
|
|
327
|
-
alreadyHadAccess: string[];
|
|
328
|
-
}
|
|
329
|
-
|
|
330
|
-
/* ── Schedules ───────────────────────────────────────────────────────────── */
|
|
331
|
-
|
|
332
|
-
/**
|
|
333
|
-
* A recurring publish an agent is expected to perform.
|
|
334
|
-
*
|
|
335
|
-
* `due` is the useful field: true once the schedule has fired and nobody has
|
|
336
|
-
* acted on that firing. Publishing a new version clears it, and so does
|
|
337
|
-
* writing a dataset — for a report that reads its numbers from `_data/…`,
|
|
338
|
-
* updating the data is the whole job.
|
|
339
|
-
*/
|
|
340
|
-
export interface ScheduleSummary {
|
|
341
|
-
id: string;
|
|
342
|
-
reportId: string;
|
|
343
|
-
reportSlug: string;
|
|
344
|
-
reportTitle: string;
|
|
345
|
-
reportUrl: string;
|
|
346
|
-
agentId: string;
|
|
347
|
-
agentName: string;
|
|
348
|
-
/** Five-field cron expression, evaluated in UTC. */
|
|
349
|
-
recurrence: string;
|
|
350
|
-
enabled: boolean;
|
|
351
|
-
lastRunAt: string | null;
|
|
352
|
-
nextRunAt: string | null;
|
|
353
|
-
currentVersion: number | null;
|
|
354
|
-
due: boolean;
|
|
355
|
-
dueSince: string | null;
|
|
356
|
-
}
|
|
357
|
-
|
|
358
|
-
/* ── Comments ────────────────────────────────────────────────────────────── */
|
|
359
|
-
|
|
360
|
-
export interface CommentThread {
|
|
361
|
-
threadId: string;
|
|
362
|
-
status: "open" | "resolved";
|
|
363
|
-
quote: string | null;
|
|
364
|
-
messages: {
|
|
365
|
-
/** What `comments.retract` takes. */
|
|
366
|
-
commentId: string;
|
|
367
|
-
author: string;
|
|
368
|
-
authorType: string;
|
|
369
|
-
body: string;
|
|
370
|
-
createdAt: string;
|
|
371
|
-
/** True for the one message this credential could still take back. */
|
|
372
|
-
retractable: boolean;
|
|
373
|
-
}[];
|
|
374
|
-
[key: string]: unknown;
|
|
375
|
-
}
|
|
376
|
-
|
|
377
|
-
/* ── Analytics ───────────────────────────────────────────────────────────── */
|
|
378
|
-
|
|
379
|
-
/** Who read one report. The detail beyond `totalViews` needs the analytics plan. */
|
|
380
|
-
export interface ReportAnalytics {
|
|
381
|
-
reportId: string;
|
|
382
|
-
title: string;
|
|
383
|
-
totalViews: number;
|
|
384
|
-
uniqueViewers: number | null;
|
|
385
|
-
internalViewers: number | null;
|
|
386
|
-
externalViewers: number | null;
|
|
387
|
-
firstViewedAt: string | null;
|
|
388
|
-
lastViewedAt: string | null;
|
|
389
|
-
byDay: { day: string; views: number; uniqueViewers: number }[];
|
|
390
|
-
byVersion: {
|
|
391
|
-
versionNumber: number;
|
|
392
|
-
views: number;
|
|
393
|
-
uniqueViewers: number;
|
|
394
|
-
lastViewedAt: string | null;
|
|
395
|
-
}[];
|
|
396
|
-
/** Names only where the organisation shows viewer identities. */
|
|
397
|
-
recentViewers: {
|
|
398
|
-
displayName: string;
|
|
399
|
-
principalType: string;
|
|
400
|
-
viewCount: number;
|
|
401
|
-
lastViewedAt: string;
|
|
402
|
-
}[];
|
|
403
|
-
}
|
|
404
|
-
|
|
405
|
-
/** What is being read across every report, and what is not being read at all. */
|
|
406
|
-
export interface OrgAnalytics {
|
|
407
|
-
days: number;
|
|
408
|
-
totalViews: number;
|
|
409
|
-
uniqueViewers: number;
|
|
410
|
-
activeReports: number;
|
|
411
|
-
externallySharedReports: number;
|
|
412
|
-
publicReports: number;
|
|
413
|
-
publishesInPeriod: number;
|
|
414
|
-
topReports: {
|
|
415
|
-
reportId: string;
|
|
416
|
-
title: string;
|
|
417
|
-
views: number;
|
|
418
|
-
uniqueViewers: number;
|
|
419
|
-
lastViewedAt: string | null;
|
|
420
|
-
}[];
|
|
421
|
-
/** Live reports with no view in the period — oldest silence first. */
|
|
422
|
-
inactiveReports: {
|
|
423
|
-
reportId: string;
|
|
424
|
-
title: string;
|
|
425
|
-
lastViewedAt: string | null;
|
|
426
|
-
publishedAt: string | null;
|
|
427
|
-
}[];
|
|
428
|
-
}
|
|
429
|
-
|
|
430
|
-
/* ── Webhooks ────────────────────────────────────────────────────────────── */
|
|
431
|
-
|
|
432
|
-
export type WebhookEventName =
|
|
433
|
-
| "report.published"
|
|
434
|
-
| "report.updated"
|
|
435
|
-
| "report.shared"
|
|
436
|
-
| "report.viewed"
|
|
437
|
-
| "comment.created"
|
|
438
|
-
| "access.requested"
|
|
439
|
-
| "schedule.due"
|
|
440
|
-
| "publish.held"
|
|
441
|
-
| "approval.requested"
|
|
442
|
-
| "approval.approved"
|
|
443
|
-
| "approval.rejected"
|
|
444
|
-
| "approval.expired"
|
|
445
|
-
| "approval.escalated"
|
|
446
|
-
| "approval.question"
|
|
447
|
-
| "approval.answered"
|
|
448
|
-
| "review.requested"
|
|
449
|
-
| "review.approved"
|
|
450
|
-
| "review.changes_requested"
|
|
451
|
-
| "collection.requested"
|
|
452
|
-
| "collection.completed"
|
|
453
|
-
| "flow.completed"
|
|
454
|
-
/** A gate refused. The only gate event that relays: an allow fires on every
|
|
455
|
-
* auto-allowed action, and an escalation already arrives as
|
|
456
|
-
* `approval.requested`. */
|
|
457
|
-
| "gate.denied";
|
|
458
|
-
|
|
459
|
-
export interface WebhookEvent {
|
|
460
|
-
event: WebhookEventName;
|
|
461
|
-
sentAt: string;
|
|
462
|
-
/** Present and true when sent by the Send test button, not by real activity. */
|
|
463
|
-
test?: boolean;
|
|
464
|
-
data: Record<string, unknown>;
|
|
465
|
-
}
|
|
466
|
-
|
|
467
|
-
/* ── Reviews ──────────────────────────────────────────────────────────────── */
|
|
468
|
-
|
|
469
|
-
export type ReviewStatus =
|
|
470
|
-
| "pending"
|
|
471
|
-
| "approved"
|
|
472
|
-
| "changes_requested"
|
|
473
|
-
| "expired"
|
|
474
|
-
| "cancelled";
|
|
475
|
-
|
|
476
|
-
export interface CreateReviewInput {
|
|
477
|
-
/** What is being reviewed, as a headline the reviewer sees first. */
|
|
478
|
-
title: string;
|
|
479
|
-
/**
|
|
480
|
-
* What to check. Without this a reviewer decides what "review" means, and
|
|
481
|
-
* usually decides it means "looks fine".
|
|
482
|
-
*/
|
|
483
|
-
instructions?: string;
|
|
484
|
-
/** The published report under review; the reviewer reads it and comments on it. */
|
|
485
|
-
reportId?: string;
|
|
486
|
-
/** Pin a version, so publishing again mid-review does not move the ground. */
|
|
487
|
-
versionId?: string;
|
|
488
|
-
/**
|
|
489
|
-
* Emails or user ids. An active member, or a guest who can already open the
|
|
490
|
-
* report — anyone else is refused rather than emailed. You cannot name
|
|
491
|
-
* yourself.
|
|
492
|
-
*/
|
|
493
|
-
reviewers: string[];
|
|
494
|
-
/**
|
|
495
|
-
* How many approvals settle it; one when omitted. A single "changes
|
|
496
|
-
* requested" settles it regardless.
|
|
497
|
-
*/
|
|
498
|
-
requiredApprovals?: number;
|
|
499
|
-
/** After this the review expires unanswered. ISO 8601. */
|
|
500
|
-
expiresAt?: string;
|
|
501
|
-
/** Your own reference, returned unchanged and searchable. */
|
|
502
|
-
externalId?: string;
|
|
503
|
-
/**
|
|
504
|
-
* The flow this belongs to, when it is one step of a larger piece of work.
|
|
505
|
-
* Must be an open flow in your organisation. `flow.approve()` and its
|
|
506
|
-
* siblings set this for you.
|
|
507
|
-
*/
|
|
508
|
-
flowId?: string;
|
|
509
|
-
metadata?: Record<string, unknown>;
|
|
510
|
-
}
|
|
511
|
-
|
|
512
|
-
export interface ReviewerRef {
|
|
513
|
-
kind: "user" | "guest";
|
|
514
|
-
id: string;
|
|
515
|
-
label: string;
|
|
516
|
-
}
|
|
517
|
-
|
|
518
|
-
export interface ReviewVerdict {
|
|
519
|
-
verdict: "approved" | "changes_requested";
|
|
520
|
-
/** Who gave it, as a name rather than an id. */
|
|
521
|
-
by: string;
|
|
522
|
-
note: string | null;
|
|
523
|
-
at: string;
|
|
524
|
-
}
|
|
525
|
-
|
|
526
|
-
export interface ReviewData {
|
|
527
|
-
id: string;
|
|
528
|
-
status: ReviewStatus;
|
|
529
|
-
/** The page the reviewer reads and decides on. */
|
|
530
|
-
url: string;
|
|
531
|
-
title: string;
|
|
532
|
-
instructions: string | null;
|
|
533
|
-
reportId: string | null;
|
|
534
|
-
versionId: string | null;
|
|
535
|
-
externalId: string | null;
|
|
536
|
-
metadata: Record<string, unknown>;
|
|
537
|
-
requestedBy: string;
|
|
538
|
-
requiredApprovals: number;
|
|
539
|
-
reviewers: ReviewerRef[];
|
|
540
|
-
verdicts: ReviewVerdict[];
|
|
541
|
-
/** How many comment threads the reviewers opened while reading. */
|
|
542
|
-
threadCount: number;
|
|
543
|
-
settledAt: string | null;
|
|
544
|
-
expiresAt: string | null;
|
|
545
|
-
createdAt: string;
|
|
546
|
-
}
|
|
547
|
-
|
|
548
|
-
/** The answer, flattened — what `review()` hands back. */
|
|
549
|
-
export interface ReviewOutcome {
|
|
550
|
-
/** The one to branch on. False for changes requested, expired and cancelled. */
|
|
551
|
-
approved: boolean;
|
|
552
|
-
status: Exclude<ReviewStatus, "pending">;
|
|
553
|
-
/** Every verdict returned, in the order they arrived. */
|
|
554
|
-
verdicts: ReviewVerdict[];
|
|
555
|
-
/** How many comment threads to read before producing the next version. */
|
|
556
|
-
threadCount: number;
|
|
557
|
-
id: string;
|
|
558
|
-
url: string;
|
|
559
|
-
review: ReviewData;
|
|
560
|
-
}
|
|
561
|
-
|
|
562
|
-
export interface ListReviewsInput {
|
|
563
|
-
status?: ReviewStatus;
|
|
564
|
-
externalId?: string;
|
|
565
|
-
reportId?: string;
|
|
566
|
-
/** One page of this size. Leave it unset to get every row. */
|
|
567
|
-
limit?: number;
|
|
568
|
-
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
569
|
-
cursor?: string;
|
|
570
|
-
}
|
|
571
|
-
|
|
572
|
-
/* ── Collections ──────────────────────────────────────────────────────────── */
|
|
573
|
-
|
|
574
|
-
export type CollectionStatus = "pending" | "complete" | "expired" | "cancelled";
|
|
575
|
-
|
|
576
|
-
export type QuestionKind =
|
|
577
|
-
| "text"
|
|
578
|
-
| "long_text"
|
|
579
|
-
| "number"
|
|
580
|
-
| "date"
|
|
581
|
-
| "choice"
|
|
582
|
-
| "multi_choice"
|
|
583
|
-
| "boolean";
|
|
584
|
-
|
|
585
|
-
/** What an answer can hold, shaped by its question's kind. */
|
|
586
|
-
export type AnswerValue = string | number | boolean | string[];
|
|
587
|
-
|
|
588
|
-
export interface QuestionInput {
|
|
589
|
-
/** The question, as you would ask it out loud. */
|
|
590
|
-
prompt: string;
|
|
591
|
-
/** The sentence under the field that stops the wrong answer being given. */
|
|
592
|
-
help?: string;
|
|
593
|
-
kind: QuestionKind;
|
|
594
|
-
/** Required unless you say otherwise; a required question blocks submission. */
|
|
595
|
-
required?: boolean;
|
|
596
|
-
/** For `choice` and `multi_choice`. At least two, or it is not a question. */
|
|
597
|
-
options?: string[];
|
|
598
|
-
}
|
|
599
|
-
|
|
600
|
-
export interface CreateCollectionInput {
|
|
601
|
-
/** What you need, as a headline the person sees first. */
|
|
602
|
-
title: string;
|
|
603
|
-
/** Why you are asking, shown above the questions. */
|
|
604
|
-
instructions?: string;
|
|
605
|
-
questions: QuestionInput[];
|
|
606
|
-
/**
|
|
607
|
-
* Emails or user ids. An active member, or a guest the organisation already
|
|
608
|
-
* knows — anyone else is refused rather than emailed.
|
|
609
|
-
*/
|
|
610
|
-
respondents: string[];
|
|
611
|
-
/** How many submitted replies complete it; everyone asked, when omitted. */
|
|
612
|
-
requiredResponses?: number;
|
|
613
|
-
/** A published report the request is about. */
|
|
614
|
-
reportId?: string;
|
|
615
|
-
/** Shown to the person, and what the single reminder is measured against. */
|
|
616
|
-
dueAt?: string;
|
|
617
|
-
/** After this the request closes unanswered. ISO 8601. */
|
|
618
|
-
expiresAt?: string;
|
|
619
|
-
externalId?: string;
|
|
620
|
-
/**
|
|
621
|
-
* The flow this belongs to, when it is one step of a larger piece of work.
|
|
622
|
-
* Must be an open flow in your organisation. `flow.approve()` and its
|
|
623
|
-
* siblings set this for you.
|
|
624
|
-
*/
|
|
625
|
-
flowId?: string;
|
|
626
|
-
metadata?: Record<string, unknown>;
|
|
627
|
-
}
|
|
628
|
-
|
|
629
|
-
export interface CollectionQuestion {
|
|
630
|
-
id: string;
|
|
631
|
-
prompt: string;
|
|
632
|
-
help: string | null;
|
|
633
|
-
kind: QuestionKind;
|
|
634
|
-
required: boolean;
|
|
635
|
-
options: string[];
|
|
636
|
-
}
|
|
637
|
-
|
|
638
|
-
export interface CollectionReply {
|
|
639
|
-
/** Who answered, as a name rather than an id. */
|
|
640
|
-
respondent: string;
|
|
641
|
-
status: "pending" | "submitted";
|
|
642
|
-
submittedAt: string | null;
|
|
643
|
-
/** Empty until they submit: a half-typed draft is not what they meant to say. */
|
|
644
|
-
answers: { question: string; kind: QuestionKind; value: AnswerValue }[];
|
|
645
|
-
}
|
|
646
|
-
|
|
647
|
-
export interface CollectionData {
|
|
648
|
-
id: string;
|
|
649
|
-
status: CollectionStatus;
|
|
650
|
-
/** The page the person fills in. */
|
|
651
|
-
url: string;
|
|
652
|
-
title: string;
|
|
653
|
-
instructions: string | null;
|
|
654
|
-
reportId: string | null;
|
|
655
|
-
externalId: string | null;
|
|
656
|
-
metadata: Record<string, unknown>;
|
|
657
|
-
requestedBy: string;
|
|
658
|
-
requiredResponses: number;
|
|
659
|
-
questions: CollectionQuestion[];
|
|
660
|
-
responses: CollectionReply[];
|
|
661
|
-
submittedCount: number;
|
|
662
|
-
askedCount: number;
|
|
663
|
-
settledAt: string | null;
|
|
664
|
-
dueAt: string | null;
|
|
665
|
-
expiresAt: string | null;
|
|
666
|
-
createdAt: string;
|
|
667
|
-
}
|
|
668
|
-
|
|
669
|
-
/** The answers, flattened — what `collect()` hands back. */
|
|
670
|
-
export interface CollectedAnswers {
|
|
671
|
-
/** True when enough people replied; false if it expired or was withdrawn. */
|
|
672
|
-
complete: boolean;
|
|
673
|
-
status: Exclude<CollectionStatus, "pending">;
|
|
674
|
-
/** Every submitted reply, in the order they arrived. */
|
|
675
|
-
responses: CollectionReply[];
|
|
676
|
-
/**
|
|
677
|
-
* The first submitted answer to each question, by its prompt — the shape
|
|
678
|
-
* most callers want when they asked one person for three facts.
|
|
679
|
-
*/
|
|
680
|
-
answers: Record<string, AnswerValue>;
|
|
681
|
-
id: string;
|
|
682
|
-
url: string;
|
|
683
|
-
collection: CollectionData;
|
|
684
|
-
}
|
|
685
|
-
|
|
686
|
-
export interface ListCollectionsInput {
|
|
687
|
-
status?: CollectionStatus;
|
|
688
|
-
externalId?: string;
|
|
689
|
-
/** One page of this size. Leave it unset to get every row. */
|
|
690
|
-
limit?: number;
|
|
691
|
-
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
692
|
-
cursor?: string;
|
|
693
|
-
}
|
|
694
|
-
|
|
695
|
-
/* ── Flows ────────────────────────────────────────────────────────────────── */
|
|
696
|
-
|
|
697
|
-
export type FlowStatus = "open" | "complete" | "cancelled";
|
|
698
|
-
export type FlowMemberKind = "approval" | "review" | "collection" | "report";
|
|
699
|
-
|
|
700
|
-
export interface FlowMember {
|
|
701
|
-
kind: FlowMemberKind;
|
|
702
|
-
id: string;
|
|
703
|
-
title: string;
|
|
704
|
-
/** The member's own status word, which differs by kind. */
|
|
705
|
-
status: string;
|
|
706
|
-
/** Still waiting on somebody. Always false for a report. */
|
|
707
|
-
open: boolean;
|
|
708
|
-
createdAt: string;
|
|
709
|
-
}
|
|
710
|
-
|
|
711
|
-
/** One line of the history: what happened, who did it, when. */
|
|
712
|
-
export interface FlowEvent {
|
|
713
|
-
event: string;
|
|
714
|
-
actor: string;
|
|
715
|
-
actorType: string;
|
|
716
|
-
resourceType: string | null;
|
|
717
|
-
resourceId: string | null;
|
|
718
|
-
at: string;
|
|
719
|
-
}
|
|
720
|
-
|
|
721
|
-
export interface FlowData {
|
|
722
|
-
id: string;
|
|
723
|
-
status: FlowStatus;
|
|
724
|
-
/** The timeline page a person can open. */
|
|
725
|
-
url: string;
|
|
726
|
-
title: string;
|
|
727
|
-
description: string | null;
|
|
728
|
-
externalId: string | null;
|
|
729
|
-
metadata: Record<string, unknown>;
|
|
730
|
-
startedBy: string;
|
|
731
|
-
members: FlowMember[];
|
|
732
|
-
memberCount: number;
|
|
733
|
-
openCount: number;
|
|
734
|
-
/** Nothing outstanding right now — not a claim that the job is finished. */
|
|
735
|
-
allSettled: boolean;
|
|
736
|
-
/** Present on a single read, absent from a list. */
|
|
737
|
-
timeline?: FlowEvent[];
|
|
738
|
-
settledAt: string | null;
|
|
739
|
-
createdAt: string;
|
|
740
|
-
}
|
|
741
|
-
|
|
742
|
-
export interface CreateFlowInput {
|
|
743
|
-
/** What this piece of work is, as the timeline will be titled. */
|
|
744
|
-
title: string;
|
|
745
|
-
/** What it is for, for whoever reads the history a year from now. */
|
|
746
|
-
description?: string;
|
|
747
|
-
workspaceId?: string;
|
|
748
|
-
/** Your own reference. Pass it and use `resume()` so a restart does not start a second flow. */
|
|
749
|
-
externalId?: string;
|
|
750
|
-
metadata?: Record<string, unknown>;
|
|
751
|
-
}
|
|
752
|
-
|
|
753
|
-
export interface ListFlowsInput {
|
|
754
|
-
status?: FlowStatus;
|
|
755
|
-
externalId?: string;
|
|
756
|
-
/** One page of this size. Leave it unset to get every row. */
|
|
757
|
-
limit?: number;
|
|
758
|
-
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
759
|
-
cursor?: string;
|
|
760
|
-
}
|
|
761
|
-
|
|
762
|
-
/* ── Evidence ─────────────────────────────────────────────────────────────── */
|
|
763
|
-
|
|
764
|
-
export type EvidenceStepKind = "approval" | "review" | "collection" | "report";
|
|
765
|
-
|
|
766
|
-
export interface EvidenceOutcome {
|
|
767
|
-
who: string;
|
|
768
|
-
/** What they said, in the words the step uses: "approved", "answered". */
|
|
769
|
-
said: string;
|
|
770
|
-
note: string | null;
|
|
771
|
-
at: string;
|
|
772
|
-
}
|
|
773
|
-
|
|
774
|
-
export interface EvidenceStep {
|
|
775
|
-
kind: EvidenceStepKind;
|
|
776
|
-
id: string;
|
|
777
|
-
title: string;
|
|
778
|
-
status: string;
|
|
779
|
-
url: string;
|
|
780
|
-
createdAt: string;
|
|
781
|
-
settledAt: string | null;
|
|
782
|
-
requestedBy: string;
|
|
783
|
-
/** Whether an agent asked for this, which is the point of the record. */
|
|
784
|
-
requestedByAgent: boolean;
|
|
785
|
-
asked: string[];
|
|
786
|
-
outcomes: EvidenceOutcome[];
|
|
787
|
-
/** Whatever else the step records: the description, the questions, the answers. */
|
|
788
|
-
detail: Record<string, unknown>;
|
|
789
|
-
}
|
|
790
|
-
|
|
791
|
-
export interface EvidenceEvent {
|
|
792
|
-
at: string;
|
|
793
|
-
event: string;
|
|
794
|
-
actor: string;
|
|
795
|
-
actorType: string;
|
|
796
|
-
/** Which step it happened to, when it happened to one. */
|
|
797
|
-
step: string | null;
|
|
798
|
-
metadata: Record<string, unknown>;
|
|
799
|
-
}
|
|
800
|
-
|
|
801
|
-
export interface EvidencePack {
|
|
802
|
-
packVersion: number;
|
|
803
|
-
generatedAt: string;
|
|
804
|
-
generatedBy: string;
|
|
805
|
-
organisation: { id: string; name: string };
|
|
806
|
-
subject: {
|
|
807
|
-
kind: "flow" | "report";
|
|
808
|
-
id: string;
|
|
809
|
-
title: string;
|
|
810
|
-
url: string;
|
|
811
|
-
status: string;
|
|
812
|
-
startedBy: string;
|
|
813
|
-
startedAt: string;
|
|
814
|
-
};
|
|
815
|
-
summary: {
|
|
816
|
-
steps: number;
|
|
817
|
-
events: number;
|
|
818
|
-
firstEventAt: string | null;
|
|
819
|
-
lastEventAt: string | null;
|
|
820
|
-
};
|
|
821
|
-
steps: EvidenceStep[];
|
|
822
|
-
timeline: EvidenceEvent[];
|
|
823
|
-
/**
|
|
824
|
-
* What the digest does and does not stand for, in the pack's own words.
|
|
825
|
-
*
|
|
826
|
-
* `covers` says it detects a file altered after export. `doesNotCover` says
|
|
827
|
-
* it makes no claim about the database. Both travel with the pack rather
|
|
828
|
-
* than living only in documentation, because a reader who sees a hash and
|
|
829
|
-
* no sentence will assume the stronger one.
|
|
830
|
-
*/
|
|
831
|
-
integrity: {
|
|
832
|
-
algorithm: "sha256";
|
|
833
|
-
digest: string;
|
|
834
|
-
covers: string;
|
|
835
|
-
doesNotCover: string;
|
|
836
|
-
recordsAreInsertOnly: boolean;
|
|
837
|
-
};
|
|
838
|
-
}
|
|
1
|
+
/**
|
|
2
|
+
* The API's objects, by hand.
|
|
3
|
+
*
|
|
4
|
+
* Not imported from the server's zod schemas on purpose: this package is
|
|
5
|
+
* published to npm and must not drag the monorepo's internals with it. The
|
|
6
|
+
* cost of that is drift, so `apps/web/src/lib/services/api-approvals.test.ts`
|
|
7
|
+
* holds these shapes to the schemas the API actually validates — a field added
|
|
8
|
+
* there and not here fails the build on the server side, where someone is
|
|
9
|
+
* looking.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled";
|
|
13
|
+
export type ApprovalRisk = "low" | "medium" | "high" | "critical";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* What a gate decision can be.
|
|
17
|
+
*
|
|
18
|
+
* Seven, and the extra four over `allowed | denied | pending` are worth the
|
|
19
|
+
* width. `allowed` and `denied` are what a *rule* said; the rest are what a
|
|
20
|
+
* *person* did about a request no rule settled. An action that went through
|
|
21
|
+
* because policy permitted it and one that went through because somebody
|
|
22
|
+
* agreed to it are not the same fact — the ratio between them is the number
|
|
23
|
+
* this whole layer exists to make computable — so collapsing them would throw
|
|
24
|
+
* away the distinction at the one place a caller can see it.
|
|
25
|
+
*/
|
|
26
|
+
export type GateStatus =
|
|
27
|
+
| "allowed"
|
|
28
|
+
| "denied"
|
|
29
|
+
| "pending"
|
|
30
|
+
| "approved"
|
|
31
|
+
| "rejected"
|
|
32
|
+
| "expired"
|
|
33
|
+
| "cancelled";
|
|
34
|
+
|
|
35
|
+
/** What a person decided about a gate, once one has. */
|
|
36
|
+
export type GateOutcomeName = "approved" | "rejected" | "cancelled" | "expired";
|
|
37
|
+
|
|
38
|
+
export interface CreateGateInput {
|
|
39
|
+
/** The registered action you are about to perform: `finance.refund`. */
|
|
40
|
+
actionId: string;
|
|
41
|
+
/** The arguments you will actually execute with. Validated against the action's schema. */
|
|
42
|
+
input: Record<string, unknown>;
|
|
43
|
+
/**
|
|
44
|
+
* Your id for this unit of work — `refund:ord_8812`. **Required**, which no
|
|
45
|
+
* other create in this SDK is.
|
|
46
|
+
*
|
|
47
|
+
* Every other POST mints a random idempotency key per attempt, which guards a
|
|
48
|
+
* retried *request*. This guards a retried *decision*: a crashed agent that
|
|
49
|
+
* re-runs its refund step must re-read the answer it already got, not ask a
|
|
50
|
+
* second person about the same money. No id the SDK invented could know which
|
|
51
|
+
* two calls are the same attempt, so you name it.
|
|
52
|
+
*/
|
|
53
|
+
externalId: string;
|
|
54
|
+
/** Where this is running, for rules that tell staging from production. */
|
|
55
|
+
environment?: string;
|
|
56
|
+
/** Why, shown to whoever is asked to decide. */
|
|
57
|
+
reason?: string;
|
|
58
|
+
flowId?: string;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export interface GateData {
|
|
62
|
+
id: string;
|
|
63
|
+
status: GateStatus;
|
|
64
|
+
/** The one to branch on: a rule permitted it, or a person agreed to it. */
|
|
65
|
+
allowed: boolean;
|
|
66
|
+
/** The input as the action's schema validated it — what to execute with. */
|
|
67
|
+
input: Record<string, unknown>;
|
|
68
|
+
/** Whether a rule decided this or a person did. */
|
|
69
|
+
basis: "policy" | "human";
|
|
70
|
+
reason: string | null;
|
|
71
|
+
/** The rule that decided, by name. Null when nothing matched. */
|
|
72
|
+
rule: string | null;
|
|
73
|
+
policyVersionId: string | null;
|
|
74
|
+
approvalId: string | null;
|
|
75
|
+
approvalUrl: string | null;
|
|
76
|
+
outcome: GateOutcomeName | null;
|
|
77
|
+
settledAt: string | null;
|
|
78
|
+
/** True when this call found a decision already made under your `externalId`. */
|
|
79
|
+
reused: boolean;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The answer, flattened — what `gate()` hands back.
|
|
84
|
+
*
|
|
85
|
+
* `allowed` is a boolean so `if (decision.allowed)` reads as the sentence it
|
|
86
|
+
* is; `status` is the narrowing union for a switch. The same pairing, for the
|
|
87
|
+
* same reason, as `Decision` on an approval.
|
|
88
|
+
*/
|
|
89
|
+
export interface GateDecision {
|
|
90
|
+
allowed: boolean;
|
|
91
|
+
status: GateStatus;
|
|
92
|
+
reason: string | null;
|
|
93
|
+
rule: string | null;
|
|
94
|
+
input: Record<string, unknown>;
|
|
95
|
+
id: string;
|
|
96
|
+
approvalUrl: string | null;
|
|
97
|
+
gate: unknown;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** One line of evidence, as the approval page shows it. */
|
|
101
|
+
export interface ApprovalFactor {
|
|
102
|
+
label: string;
|
|
103
|
+
status?: "ok" | "warning" | "info";
|
|
104
|
+
detail?: string;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export interface ApprovalLink {
|
|
108
|
+
label: string;
|
|
109
|
+
url: string;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
export interface ApprovalQuestion {
|
|
113
|
+
id: string;
|
|
114
|
+
question: string;
|
|
115
|
+
answer: string | null;
|
|
116
|
+
askedAt: string;
|
|
117
|
+
answeredAt: string | null;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
export interface ApprovalData {
|
|
121
|
+
id: string;
|
|
122
|
+
status: ApprovalStatus;
|
|
123
|
+
/** The page the approver decides on. */
|
|
124
|
+
url: string;
|
|
125
|
+
title: string;
|
|
126
|
+
description: string | null;
|
|
127
|
+
risk: ApprovalRisk;
|
|
128
|
+
factors: ApprovalFactor[];
|
|
129
|
+
links: ApprovalLink[];
|
|
130
|
+
reportId: string | null;
|
|
131
|
+
externalId: string | null;
|
|
132
|
+
metadata: Record<string, unknown>;
|
|
133
|
+
requestedBy: string;
|
|
134
|
+
approvers: string[];
|
|
135
|
+
/**
|
|
136
|
+
* How many people must agree before it settles. One unless a standing rule
|
|
137
|
+
* in the organisation escalated it — an agent cannot set this, and a rule
|
|
138
|
+
* can only push it up.
|
|
139
|
+
*/
|
|
140
|
+
requiredApprovals: number;
|
|
141
|
+
/** How many have approved so far. Compare with `requiredApprovals`. */
|
|
142
|
+
approvalsSoFar: number;
|
|
143
|
+
/** Who decided, as a name rather than an id — the same as a review's `by`. */
|
|
144
|
+
decidedBy: string | null;
|
|
145
|
+
/** Their user id, for anything that needs the key rather than the person. */
|
|
146
|
+
decidedById: string | null;
|
|
147
|
+
decidedAt: string | null;
|
|
148
|
+
/** The approver's reason, on a rejection or an approval that carried one. */
|
|
149
|
+
note: string | null;
|
|
150
|
+
expiresAt: string | null;
|
|
151
|
+
questions: ApprovalQuestion[];
|
|
152
|
+
createdAt: string;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
export interface CreateApprovalInput {
|
|
156
|
+
/** What is being asked, as a headline. */
|
|
157
|
+
title: string;
|
|
158
|
+
/** Why, what it affects, what it costs — what the approver reads first. */
|
|
159
|
+
description?: string;
|
|
160
|
+
/** How the approver should weigh it. Medium when omitted. */
|
|
161
|
+
risk?: ApprovalRisk;
|
|
162
|
+
/** Evidence, one line each, shown as a checklist. */
|
|
163
|
+
factors?: ApprovalFactor[];
|
|
164
|
+
/** Where to read more. */
|
|
165
|
+
links?: ApprovalLink[];
|
|
166
|
+
/** A published report the request is about. */
|
|
167
|
+
reportId?: string;
|
|
168
|
+
/**
|
|
169
|
+
* Who may decide. Each entry is a person — an email or a user id — or the
|
|
170
|
+
* name of a directory group or workspace, or a word meaning the whole
|
|
171
|
+
* organisation ("everyone"). Naming a team is usually what you want: a
|
|
172
|
+
* request addressed to one person waits for that person to come back from
|
|
173
|
+
* holiday, and anyone on a team can answer.
|
|
174
|
+
*
|
|
175
|
+
* The organisation's owners and admins decide when this is omitted. You
|
|
176
|
+
* cannot name only yourself; being *on* a team you address is fine and means
|
|
177
|
+
* the rest of it. A name matching both a person and a team is refused rather
|
|
178
|
+
* than guessed — name it by id.
|
|
179
|
+
*/
|
|
180
|
+
approvers?: string[];
|
|
181
|
+
/** After this the request expires undecided. ISO 8601. */
|
|
182
|
+
expiresAt?: string;
|
|
183
|
+
/** Your own reference, returned unchanged and searchable. */
|
|
184
|
+
externalId?: string;
|
|
185
|
+
/**
|
|
186
|
+
* The flow this belongs to, when it is one step of a larger piece of work.
|
|
187
|
+
* Must be an open flow in your organisation. `flow.approve()` and its
|
|
188
|
+
* siblings set this for you.
|
|
189
|
+
*/
|
|
190
|
+
flowId?: string;
|
|
191
|
+
metadata?: Record<string, unknown>;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* The answer to `approve()`.
|
|
196
|
+
*
|
|
197
|
+
* Flat on purpose: the line after the call is `if (decision.approved)`, and
|
|
198
|
+
* anything a caller has to reach through to get there is a step this SDK
|
|
199
|
+
* exists to remove. The whole request is on `approval` when a field here does
|
|
200
|
+
* not cover it.
|
|
201
|
+
*/
|
|
202
|
+
export type Decision = {
|
|
203
|
+
/** True only for an approval. False for rejected, expired and cancelled. */
|
|
204
|
+
approved: boolean;
|
|
205
|
+
/** For a switch, and for narrowing. */
|
|
206
|
+
status: "approved" | "rejected" | "expired" | "cancelled";
|
|
207
|
+
/** Their reason, when they gave one. */
|
|
208
|
+
note: string | null;
|
|
209
|
+
/** Who decided, as a name rather than an id. Log it; put it in a message. */
|
|
210
|
+
decidedBy: string | null;
|
|
211
|
+
/** Their user id, when the key is what you need. */
|
|
212
|
+
decidedById: string | null;
|
|
213
|
+
decidedAt: string | null;
|
|
214
|
+
id: string;
|
|
215
|
+
/** The page they decided on. Worth logging. */
|
|
216
|
+
url: string;
|
|
217
|
+
/** The request itself, for anything the fields above do not name. */
|
|
218
|
+
approval: unknown;
|
|
219
|
+
};
|
|
220
|
+
|
|
221
|
+
export interface ListApprovalsInput {
|
|
222
|
+
status?: ApprovalStatus;
|
|
223
|
+
externalId?: string;
|
|
224
|
+
/** One page of this size. Leave it unset to get every row. */
|
|
225
|
+
limit?: number;
|
|
226
|
+
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
227
|
+
cursor?: string;
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/* ── Reports ─────────────────────────────────────────────────────────────── */
|
|
231
|
+
|
|
232
|
+
export interface InlineFile {
|
|
233
|
+
path: string;
|
|
234
|
+
content: string;
|
|
235
|
+
/** `base64` for an image or a font; text otherwise. */
|
|
236
|
+
encoding?: "utf8" | "base64";
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
export interface PublishReportInput {
|
|
240
|
+
title?: string;
|
|
241
|
+
slug?: string;
|
|
242
|
+
description?: string;
|
|
243
|
+
workspaceId?: string;
|
|
244
|
+
/** Names, teams, groups or emails — resolved server-side. */
|
|
245
|
+
audience?: unknown;
|
|
246
|
+
classification?: string;
|
|
247
|
+
living?: boolean;
|
|
248
|
+
sourceTool?: string;
|
|
249
|
+
sourceModel?: string;
|
|
250
|
+
changeSummary?: string;
|
|
251
|
+
/** Publish only if this is still the current version; 0 claims a new slug. */
|
|
252
|
+
expectedVersion?: number;
|
|
253
|
+
uploadId?: string;
|
|
254
|
+
content?: string;
|
|
255
|
+
files?: InlineFile[];
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
export type UpdateReportInput = Pick<
|
|
259
|
+
PublishReportInput,
|
|
260
|
+
| "uploadId"
|
|
261
|
+
| "content"
|
|
262
|
+
| "files"
|
|
263
|
+
| "title"
|
|
264
|
+
| "description"
|
|
265
|
+
| "sourceTool"
|
|
266
|
+
| "sourceModel"
|
|
267
|
+
| "changeSummary"
|
|
268
|
+
| "expectedVersion"
|
|
269
|
+
>;
|
|
270
|
+
|
|
271
|
+
export interface ReportData {
|
|
272
|
+
id: string;
|
|
273
|
+
slug: string;
|
|
274
|
+
title: string;
|
|
275
|
+
url: string;
|
|
276
|
+
status: string;
|
|
277
|
+
currentVersion: number | null;
|
|
278
|
+
[key: string]: unknown;
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
/**
|
|
282
|
+
* A publish held by a policy rule answers 202 with this instead of going live.
|
|
283
|
+
* `status` says which happened, so a caller that ignores it still gets a
|
|
284
|
+
* report object and a caller that reads it knows nobody can see the thing yet.
|
|
285
|
+
*/
|
|
286
|
+
export interface PublishResult {
|
|
287
|
+
status?: "published" | "updated" | "pending_approval";
|
|
288
|
+
report: ReportData;
|
|
289
|
+
version?: { id: string; versionNumber: number; [key: string]: unknown };
|
|
290
|
+
approval?: { id: string; status: string };
|
|
291
|
+
warnings?: string[];
|
|
292
|
+
[key: string]: unknown;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/**
|
|
296
|
+
* One open thread, as the organisation-wide list returns it.
|
|
297
|
+
*
|
|
298
|
+
* Deliberately thinner than a `CommentThread`: this answers "where is the
|
|
299
|
+
* feedback" across every report, so it carries the report and the quoted
|
|
300
|
+
* passage rather than the whole conversation. Fetch the thread itself with
|
|
301
|
+
* `comments.list(reportId)` once you know which report to look at.
|
|
302
|
+
*/
|
|
303
|
+
export interface OpenThread {
|
|
304
|
+
threadId: string;
|
|
305
|
+
reportId: string;
|
|
306
|
+
reportTitle: string;
|
|
307
|
+
reportSlug: string;
|
|
308
|
+
/** Who owns the report — filter on it to find the threads on yours. */
|
|
309
|
+
reportOwnerId: string | null;
|
|
310
|
+
quote: string | null;
|
|
311
|
+
author: string;
|
|
312
|
+
authorType: string;
|
|
313
|
+
messages: number;
|
|
314
|
+
lastActivityAt: string;
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
/**
|
|
318
|
+
* What a send did, per address.
|
|
319
|
+
*
|
|
320
|
+
* `delivered` is the mail provider accepting it, not the person reading it —
|
|
321
|
+
* and `alreadyHadAccess` names the recipients who could already open the
|
|
322
|
+
* report, who were emailed again anyway. Re-sending to somebody who says
|
|
323
|
+
* they never got the first one is the point.
|
|
324
|
+
*/
|
|
325
|
+
export interface SendResult {
|
|
326
|
+
sent: { email: string; delivered: boolean }[];
|
|
327
|
+
alreadyHadAccess: string[];
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
/* ── Schedules ───────────────────────────────────────────────────────────── */
|
|
331
|
+
|
|
332
|
+
/**
|
|
333
|
+
* A recurring publish an agent is expected to perform.
|
|
334
|
+
*
|
|
335
|
+
* `due` is the useful field: true once the schedule has fired and nobody has
|
|
336
|
+
* acted on that firing. Publishing a new version clears it, and so does
|
|
337
|
+
* writing a dataset — for a report that reads its numbers from `_data/…`,
|
|
338
|
+
* updating the data is the whole job.
|
|
339
|
+
*/
|
|
340
|
+
export interface ScheduleSummary {
|
|
341
|
+
id: string;
|
|
342
|
+
reportId: string;
|
|
343
|
+
reportSlug: string;
|
|
344
|
+
reportTitle: string;
|
|
345
|
+
reportUrl: string;
|
|
346
|
+
agentId: string;
|
|
347
|
+
agentName: string;
|
|
348
|
+
/** Five-field cron expression, evaluated in UTC. */
|
|
349
|
+
recurrence: string;
|
|
350
|
+
enabled: boolean;
|
|
351
|
+
lastRunAt: string | null;
|
|
352
|
+
nextRunAt: string | null;
|
|
353
|
+
currentVersion: number | null;
|
|
354
|
+
due: boolean;
|
|
355
|
+
dueSince: string | null;
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
/* ── Comments ────────────────────────────────────────────────────────────── */
|
|
359
|
+
|
|
360
|
+
export interface CommentThread {
|
|
361
|
+
threadId: string;
|
|
362
|
+
status: "open" | "resolved";
|
|
363
|
+
quote: string | null;
|
|
364
|
+
messages: {
|
|
365
|
+
/** What `comments.retract` takes. */
|
|
366
|
+
commentId: string;
|
|
367
|
+
author: string;
|
|
368
|
+
authorType: string;
|
|
369
|
+
body: string;
|
|
370
|
+
createdAt: string;
|
|
371
|
+
/** True for the one message this credential could still take back. */
|
|
372
|
+
retractable: boolean;
|
|
373
|
+
}[];
|
|
374
|
+
[key: string]: unknown;
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
/* ── Analytics ───────────────────────────────────────────────────────────── */
|
|
378
|
+
|
|
379
|
+
/** Who read one report. The detail beyond `totalViews` needs the analytics plan. */
|
|
380
|
+
export interface ReportAnalytics {
|
|
381
|
+
reportId: string;
|
|
382
|
+
title: string;
|
|
383
|
+
totalViews: number;
|
|
384
|
+
uniqueViewers: number | null;
|
|
385
|
+
internalViewers: number | null;
|
|
386
|
+
externalViewers: number | null;
|
|
387
|
+
firstViewedAt: string | null;
|
|
388
|
+
lastViewedAt: string | null;
|
|
389
|
+
byDay: { day: string; views: number; uniqueViewers: number }[];
|
|
390
|
+
byVersion: {
|
|
391
|
+
versionNumber: number;
|
|
392
|
+
views: number;
|
|
393
|
+
uniqueViewers: number;
|
|
394
|
+
lastViewedAt: string | null;
|
|
395
|
+
}[];
|
|
396
|
+
/** Names only where the organisation shows viewer identities. */
|
|
397
|
+
recentViewers: {
|
|
398
|
+
displayName: string;
|
|
399
|
+
principalType: string;
|
|
400
|
+
viewCount: number;
|
|
401
|
+
lastViewedAt: string;
|
|
402
|
+
}[];
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
/** What is being read across every report, and what is not being read at all. */
|
|
406
|
+
export interface OrgAnalytics {
|
|
407
|
+
days: number;
|
|
408
|
+
totalViews: number;
|
|
409
|
+
uniqueViewers: number;
|
|
410
|
+
activeReports: number;
|
|
411
|
+
externallySharedReports: number;
|
|
412
|
+
publicReports: number;
|
|
413
|
+
publishesInPeriod: number;
|
|
414
|
+
topReports: {
|
|
415
|
+
reportId: string;
|
|
416
|
+
title: string;
|
|
417
|
+
views: number;
|
|
418
|
+
uniqueViewers: number;
|
|
419
|
+
lastViewedAt: string | null;
|
|
420
|
+
}[];
|
|
421
|
+
/** Live reports with no view in the period — oldest silence first. */
|
|
422
|
+
inactiveReports: {
|
|
423
|
+
reportId: string;
|
|
424
|
+
title: string;
|
|
425
|
+
lastViewedAt: string | null;
|
|
426
|
+
publishedAt: string | null;
|
|
427
|
+
}[];
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
/* ── Webhooks ────────────────────────────────────────────────────────────── */
|
|
431
|
+
|
|
432
|
+
export type WebhookEventName =
|
|
433
|
+
| "report.published"
|
|
434
|
+
| "report.updated"
|
|
435
|
+
| "report.shared"
|
|
436
|
+
| "report.viewed"
|
|
437
|
+
| "comment.created"
|
|
438
|
+
| "access.requested"
|
|
439
|
+
| "schedule.due"
|
|
440
|
+
| "publish.held"
|
|
441
|
+
| "approval.requested"
|
|
442
|
+
| "approval.approved"
|
|
443
|
+
| "approval.rejected"
|
|
444
|
+
| "approval.expired"
|
|
445
|
+
| "approval.escalated"
|
|
446
|
+
| "approval.question"
|
|
447
|
+
| "approval.answered"
|
|
448
|
+
| "review.requested"
|
|
449
|
+
| "review.approved"
|
|
450
|
+
| "review.changes_requested"
|
|
451
|
+
| "collection.requested"
|
|
452
|
+
| "collection.completed"
|
|
453
|
+
| "flow.completed"
|
|
454
|
+
/** A gate refused. The only gate event that relays: an allow fires on every
|
|
455
|
+
* auto-allowed action, and an escalation already arrives as
|
|
456
|
+
* `approval.requested`. */
|
|
457
|
+
| "gate.denied";
|
|
458
|
+
|
|
459
|
+
export interface WebhookEvent {
|
|
460
|
+
event: WebhookEventName;
|
|
461
|
+
sentAt: string;
|
|
462
|
+
/** Present and true when sent by the Send test button, not by real activity. */
|
|
463
|
+
test?: boolean;
|
|
464
|
+
data: Record<string, unknown>;
|
|
465
|
+
}
|
|
466
|
+
|
|
467
|
+
/* ── Reviews ──────────────────────────────────────────────────────────────── */
|
|
468
|
+
|
|
469
|
+
export type ReviewStatus =
|
|
470
|
+
| "pending"
|
|
471
|
+
| "approved"
|
|
472
|
+
| "changes_requested"
|
|
473
|
+
| "expired"
|
|
474
|
+
| "cancelled";
|
|
475
|
+
|
|
476
|
+
export interface CreateReviewInput {
|
|
477
|
+
/** What is being reviewed, as a headline the reviewer sees first. */
|
|
478
|
+
title: string;
|
|
479
|
+
/**
|
|
480
|
+
* What to check. Without this a reviewer decides what "review" means, and
|
|
481
|
+
* usually decides it means "looks fine".
|
|
482
|
+
*/
|
|
483
|
+
instructions?: string;
|
|
484
|
+
/** The published report under review; the reviewer reads it and comments on it. */
|
|
485
|
+
reportId?: string;
|
|
486
|
+
/** Pin a version, so publishing again mid-review does not move the ground. */
|
|
487
|
+
versionId?: string;
|
|
488
|
+
/**
|
|
489
|
+
* Emails or user ids. An active member, or a guest who can already open the
|
|
490
|
+
* report — anyone else is refused rather than emailed. You cannot name
|
|
491
|
+
* yourself.
|
|
492
|
+
*/
|
|
493
|
+
reviewers: string[];
|
|
494
|
+
/**
|
|
495
|
+
* How many approvals settle it; one when omitted. A single "changes
|
|
496
|
+
* requested" settles it regardless.
|
|
497
|
+
*/
|
|
498
|
+
requiredApprovals?: number;
|
|
499
|
+
/** After this the review expires unanswered. ISO 8601. */
|
|
500
|
+
expiresAt?: string;
|
|
501
|
+
/** Your own reference, returned unchanged and searchable. */
|
|
502
|
+
externalId?: string;
|
|
503
|
+
/**
|
|
504
|
+
* The flow this belongs to, when it is one step of a larger piece of work.
|
|
505
|
+
* Must be an open flow in your organisation. `flow.approve()` and its
|
|
506
|
+
* siblings set this for you.
|
|
507
|
+
*/
|
|
508
|
+
flowId?: string;
|
|
509
|
+
metadata?: Record<string, unknown>;
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
export interface ReviewerRef {
|
|
513
|
+
kind: "user" | "guest";
|
|
514
|
+
id: string;
|
|
515
|
+
label: string;
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
export interface ReviewVerdict {
|
|
519
|
+
verdict: "approved" | "changes_requested";
|
|
520
|
+
/** Who gave it, as a name rather than an id. */
|
|
521
|
+
by: string;
|
|
522
|
+
note: string | null;
|
|
523
|
+
at: string;
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
export interface ReviewData {
|
|
527
|
+
id: string;
|
|
528
|
+
status: ReviewStatus;
|
|
529
|
+
/** The page the reviewer reads and decides on. */
|
|
530
|
+
url: string;
|
|
531
|
+
title: string;
|
|
532
|
+
instructions: string | null;
|
|
533
|
+
reportId: string | null;
|
|
534
|
+
versionId: string | null;
|
|
535
|
+
externalId: string | null;
|
|
536
|
+
metadata: Record<string, unknown>;
|
|
537
|
+
requestedBy: string;
|
|
538
|
+
requiredApprovals: number;
|
|
539
|
+
reviewers: ReviewerRef[];
|
|
540
|
+
verdicts: ReviewVerdict[];
|
|
541
|
+
/** How many comment threads the reviewers opened while reading. */
|
|
542
|
+
threadCount: number;
|
|
543
|
+
settledAt: string | null;
|
|
544
|
+
expiresAt: string | null;
|
|
545
|
+
createdAt: string;
|
|
546
|
+
}
|
|
547
|
+
|
|
548
|
+
/** The answer, flattened — what `review()` hands back. */
|
|
549
|
+
export interface ReviewOutcome {
|
|
550
|
+
/** The one to branch on. False for changes requested, expired and cancelled. */
|
|
551
|
+
approved: boolean;
|
|
552
|
+
status: Exclude<ReviewStatus, "pending">;
|
|
553
|
+
/** Every verdict returned, in the order they arrived. */
|
|
554
|
+
verdicts: ReviewVerdict[];
|
|
555
|
+
/** How many comment threads to read before producing the next version. */
|
|
556
|
+
threadCount: number;
|
|
557
|
+
id: string;
|
|
558
|
+
url: string;
|
|
559
|
+
review: ReviewData;
|
|
560
|
+
}
|
|
561
|
+
|
|
562
|
+
export interface ListReviewsInput {
|
|
563
|
+
status?: ReviewStatus;
|
|
564
|
+
externalId?: string;
|
|
565
|
+
reportId?: string;
|
|
566
|
+
/** One page of this size. Leave it unset to get every row. */
|
|
567
|
+
limit?: number;
|
|
568
|
+
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
569
|
+
cursor?: string;
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
/* ── Collections ──────────────────────────────────────────────────────────── */
|
|
573
|
+
|
|
574
|
+
export type CollectionStatus = "pending" | "complete" | "expired" | "cancelled";
|
|
575
|
+
|
|
576
|
+
export type QuestionKind =
|
|
577
|
+
| "text"
|
|
578
|
+
| "long_text"
|
|
579
|
+
| "number"
|
|
580
|
+
| "date"
|
|
581
|
+
| "choice"
|
|
582
|
+
| "multi_choice"
|
|
583
|
+
| "boolean";
|
|
584
|
+
|
|
585
|
+
/** What an answer can hold, shaped by its question's kind. */
|
|
586
|
+
export type AnswerValue = string | number | boolean | string[];
|
|
587
|
+
|
|
588
|
+
export interface QuestionInput {
|
|
589
|
+
/** The question, as you would ask it out loud. */
|
|
590
|
+
prompt: string;
|
|
591
|
+
/** The sentence under the field that stops the wrong answer being given. */
|
|
592
|
+
help?: string;
|
|
593
|
+
kind: QuestionKind;
|
|
594
|
+
/** Required unless you say otherwise; a required question blocks submission. */
|
|
595
|
+
required?: boolean;
|
|
596
|
+
/** For `choice` and `multi_choice`. At least two, or it is not a question. */
|
|
597
|
+
options?: string[];
|
|
598
|
+
}
|
|
599
|
+
|
|
600
|
+
export interface CreateCollectionInput {
|
|
601
|
+
/** What you need, as a headline the person sees first. */
|
|
602
|
+
title: string;
|
|
603
|
+
/** Why you are asking, shown above the questions. */
|
|
604
|
+
instructions?: string;
|
|
605
|
+
questions: QuestionInput[];
|
|
606
|
+
/**
|
|
607
|
+
* Emails or user ids. An active member, or a guest the organisation already
|
|
608
|
+
* knows — anyone else is refused rather than emailed.
|
|
609
|
+
*/
|
|
610
|
+
respondents: string[];
|
|
611
|
+
/** How many submitted replies complete it; everyone asked, when omitted. */
|
|
612
|
+
requiredResponses?: number;
|
|
613
|
+
/** A published report the request is about. */
|
|
614
|
+
reportId?: string;
|
|
615
|
+
/** Shown to the person, and what the single reminder is measured against. */
|
|
616
|
+
dueAt?: string;
|
|
617
|
+
/** After this the request closes unanswered. ISO 8601. */
|
|
618
|
+
expiresAt?: string;
|
|
619
|
+
externalId?: string;
|
|
620
|
+
/**
|
|
621
|
+
* The flow this belongs to, when it is one step of a larger piece of work.
|
|
622
|
+
* Must be an open flow in your organisation. `flow.approve()` and its
|
|
623
|
+
* siblings set this for you.
|
|
624
|
+
*/
|
|
625
|
+
flowId?: string;
|
|
626
|
+
metadata?: Record<string, unknown>;
|
|
627
|
+
}
|
|
628
|
+
|
|
629
|
+
export interface CollectionQuestion {
|
|
630
|
+
id: string;
|
|
631
|
+
prompt: string;
|
|
632
|
+
help: string | null;
|
|
633
|
+
kind: QuestionKind;
|
|
634
|
+
required: boolean;
|
|
635
|
+
options: string[];
|
|
636
|
+
}
|
|
637
|
+
|
|
638
|
+
export interface CollectionReply {
|
|
639
|
+
/** Who answered, as a name rather than an id. */
|
|
640
|
+
respondent: string;
|
|
641
|
+
status: "pending" | "submitted";
|
|
642
|
+
submittedAt: string | null;
|
|
643
|
+
/** Empty until they submit: a half-typed draft is not what they meant to say. */
|
|
644
|
+
answers: { question: string; kind: QuestionKind; value: AnswerValue }[];
|
|
645
|
+
}
|
|
646
|
+
|
|
647
|
+
export interface CollectionData {
|
|
648
|
+
id: string;
|
|
649
|
+
status: CollectionStatus;
|
|
650
|
+
/** The page the person fills in. */
|
|
651
|
+
url: string;
|
|
652
|
+
title: string;
|
|
653
|
+
instructions: string | null;
|
|
654
|
+
reportId: string | null;
|
|
655
|
+
externalId: string | null;
|
|
656
|
+
metadata: Record<string, unknown>;
|
|
657
|
+
requestedBy: string;
|
|
658
|
+
requiredResponses: number;
|
|
659
|
+
questions: CollectionQuestion[];
|
|
660
|
+
responses: CollectionReply[];
|
|
661
|
+
submittedCount: number;
|
|
662
|
+
askedCount: number;
|
|
663
|
+
settledAt: string | null;
|
|
664
|
+
dueAt: string | null;
|
|
665
|
+
expiresAt: string | null;
|
|
666
|
+
createdAt: string;
|
|
667
|
+
}
|
|
668
|
+
|
|
669
|
+
/** The answers, flattened — what `collect()` hands back. */
|
|
670
|
+
export interface CollectedAnswers {
|
|
671
|
+
/** True when enough people replied; false if it expired or was withdrawn. */
|
|
672
|
+
complete: boolean;
|
|
673
|
+
status: Exclude<CollectionStatus, "pending">;
|
|
674
|
+
/** Every submitted reply, in the order they arrived. */
|
|
675
|
+
responses: CollectionReply[];
|
|
676
|
+
/**
|
|
677
|
+
* The first submitted answer to each question, by its prompt — the shape
|
|
678
|
+
* most callers want when they asked one person for three facts.
|
|
679
|
+
*/
|
|
680
|
+
answers: Record<string, AnswerValue>;
|
|
681
|
+
id: string;
|
|
682
|
+
url: string;
|
|
683
|
+
collection: CollectionData;
|
|
684
|
+
}
|
|
685
|
+
|
|
686
|
+
export interface ListCollectionsInput {
|
|
687
|
+
status?: CollectionStatus;
|
|
688
|
+
externalId?: string;
|
|
689
|
+
/** One page of this size. Leave it unset to get every row. */
|
|
690
|
+
limit?: number;
|
|
691
|
+
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
692
|
+
cursor?: string;
|
|
693
|
+
}
|
|
694
|
+
|
|
695
|
+
/* ── Flows ────────────────────────────────────────────────────────────────── */
|
|
696
|
+
|
|
697
|
+
export type FlowStatus = "open" | "complete" | "cancelled";
|
|
698
|
+
export type FlowMemberKind = "approval" | "review" | "collection" | "report";
|
|
699
|
+
|
|
700
|
+
export interface FlowMember {
|
|
701
|
+
kind: FlowMemberKind;
|
|
702
|
+
id: string;
|
|
703
|
+
title: string;
|
|
704
|
+
/** The member's own status word, which differs by kind. */
|
|
705
|
+
status: string;
|
|
706
|
+
/** Still waiting on somebody. Always false for a report. */
|
|
707
|
+
open: boolean;
|
|
708
|
+
createdAt: string;
|
|
709
|
+
}
|
|
710
|
+
|
|
711
|
+
/** One line of the history: what happened, who did it, when. */
|
|
712
|
+
export interface FlowEvent {
|
|
713
|
+
event: string;
|
|
714
|
+
actor: string;
|
|
715
|
+
actorType: string;
|
|
716
|
+
resourceType: string | null;
|
|
717
|
+
resourceId: string | null;
|
|
718
|
+
at: string;
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
export interface FlowData {
|
|
722
|
+
id: string;
|
|
723
|
+
status: FlowStatus;
|
|
724
|
+
/** The timeline page a person can open. */
|
|
725
|
+
url: string;
|
|
726
|
+
title: string;
|
|
727
|
+
description: string | null;
|
|
728
|
+
externalId: string | null;
|
|
729
|
+
metadata: Record<string, unknown>;
|
|
730
|
+
startedBy: string;
|
|
731
|
+
members: FlowMember[];
|
|
732
|
+
memberCount: number;
|
|
733
|
+
openCount: number;
|
|
734
|
+
/** Nothing outstanding right now — not a claim that the job is finished. */
|
|
735
|
+
allSettled: boolean;
|
|
736
|
+
/** Present on a single read, absent from a list. */
|
|
737
|
+
timeline?: FlowEvent[];
|
|
738
|
+
settledAt: string | null;
|
|
739
|
+
createdAt: string;
|
|
740
|
+
}
|
|
741
|
+
|
|
742
|
+
export interface CreateFlowInput {
|
|
743
|
+
/** What this piece of work is, as the timeline will be titled. */
|
|
744
|
+
title: string;
|
|
745
|
+
/** What it is for, for whoever reads the history a year from now. */
|
|
746
|
+
description?: string;
|
|
747
|
+
workspaceId?: string;
|
|
748
|
+
/** Your own reference. Pass it and use `resume()` so a restart does not start a second flow. */
|
|
749
|
+
externalId?: string;
|
|
750
|
+
metadata?: Record<string, unknown>;
|
|
751
|
+
}
|
|
752
|
+
|
|
753
|
+
export interface ListFlowsInput {
|
|
754
|
+
status?: FlowStatus;
|
|
755
|
+
externalId?: string;
|
|
756
|
+
/** One page of this size. Leave it unset to get every row. */
|
|
757
|
+
limit?: number;
|
|
758
|
+
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
759
|
+
cursor?: string;
|
|
760
|
+
}
|
|
761
|
+
|
|
762
|
+
/* ── Evidence ─────────────────────────────────────────────────────────────── */
|
|
763
|
+
|
|
764
|
+
export type EvidenceStepKind = "approval" | "review" | "collection" | "report";
|
|
765
|
+
|
|
766
|
+
export interface EvidenceOutcome {
|
|
767
|
+
who: string;
|
|
768
|
+
/** What they said, in the words the step uses: "approved", "answered". */
|
|
769
|
+
said: string;
|
|
770
|
+
note: string | null;
|
|
771
|
+
at: string;
|
|
772
|
+
}
|
|
773
|
+
|
|
774
|
+
export interface EvidenceStep {
|
|
775
|
+
kind: EvidenceStepKind;
|
|
776
|
+
id: string;
|
|
777
|
+
title: string;
|
|
778
|
+
status: string;
|
|
779
|
+
url: string;
|
|
780
|
+
createdAt: string;
|
|
781
|
+
settledAt: string | null;
|
|
782
|
+
requestedBy: string;
|
|
783
|
+
/** Whether an agent asked for this, which is the point of the record. */
|
|
784
|
+
requestedByAgent: boolean;
|
|
785
|
+
asked: string[];
|
|
786
|
+
outcomes: EvidenceOutcome[];
|
|
787
|
+
/** Whatever else the step records: the description, the questions, the answers. */
|
|
788
|
+
detail: Record<string, unknown>;
|
|
789
|
+
}
|
|
790
|
+
|
|
791
|
+
export interface EvidenceEvent {
|
|
792
|
+
at: string;
|
|
793
|
+
event: string;
|
|
794
|
+
actor: string;
|
|
795
|
+
actorType: string;
|
|
796
|
+
/** Which step it happened to, when it happened to one. */
|
|
797
|
+
step: string | null;
|
|
798
|
+
metadata: Record<string, unknown>;
|
|
799
|
+
}
|
|
800
|
+
|
|
801
|
+
export interface EvidencePack {
|
|
802
|
+
packVersion: number;
|
|
803
|
+
generatedAt: string;
|
|
804
|
+
generatedBy: string;
|
|
805
|
+
organisation: { id: string; name: string };
|
|
806
|
+
subject: {
|
|
807
|
+
kind: "flow" | "report";
|
|
808
|
+
id: string;
|
|
809
|
+
title: string;
|
|
810
|
+
url: string;
|
|
811
|
+
status: string;
|
|
812
|
+
startedBy: string;
|
|
813
|
+
startedAt: string;
|
|
814
|
+
};
|
|
815
|
+
summary: {
|
|
816
|
+
steps: number;
|
|
817
|
+
events: number;
|
|
818
|
+
firstEventAt: string | null;
|
|
819
|
+
lastEventAt: string | null;
|
|
820
|
+
};
|
|
821
|
+
steps: EvidenceStep[];
|
|
822
|
+
timeline: EvidenceEvent[];
|
|
823
|
+
/**
|
|
824
|
+
* What the digest does and does not stand for, in the pack's own words.
|
|
825
|
+
*
|
|
826
|
+
* `covers` says it detects a file altered after export. `doesNotCover` says
|
|
827
|
+
* it makes no claim about the database. Both travel with the pack rather
|
|
828
|
+
* than living only in documentation, because a reader who sees a hash and
|
|
829
|
+
* no sentence will assume the stronger one.
|
|
830
|
+
*/
|
|
831
|
+
integrity: {
|
|
832
|
+
algorithm: "sha256";
|
|
833
|
+
digest: string;
|
|
834
|
+
covers: string;
|
|
835
|
+
doesNotCover: string;
|
|
836
|
+
recordsAreInsertOnly: boolean;
|
|
837
|
+
};
|
|
838
|
+
}
|