@deliverd/sdk 0.6.1 → 0.7.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/README.md +67 -2
- package/dist/approvals.d.ts +12 -0
- package/dist/approvals.d.ts.map +1 -1
- package/dist/approvals.js +33 -4
- package/dist/collections.d.ts +10 -0
- package/dist/collections.d.ts.map +1 -1
- package/dist/collections.js +18 -3
- package/dist/dev.d.ts.map +1 -1
- package/dist/dev.js +16 -3
- package/dist/flows.d.ts +10 -0
- package/dist/flows.d.ts.map +1 -1
- package/dist/flows.js +18 -3
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -2
- package/dist/messages.d.ts.map +1 -1
- package/dist/messages.js +8 -4
- package/dist/paging.d.ts +43 -0
- package/dist/paging.d.ts.map +1 -0
- package/dist/paging.js +27 -0
- package/dist/released.d.ts +29 -0
- package/dist/released.d.ts.map +1 -0
- package/dist/released.js +402 -0
- package/dist/reports.d.ts +152 -4
- package/dist/reports.d.ts.map +1 -1
- package/dist/reports.js +209 -10
- package/dist/reviews.d.ts +10 -0
- package/dist/reviews.d.ts.map +1 -1
- package/dist/reviews.js +18 -8
- package/dist/types.d.ts +147 -3
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/approvals.ts +40 -4
- package/src/collections.ts +25 -3
- package/src/dev.ts +16 -3
- package/src/flows.ts +25 -3
- package/src/index.ts +4 -2
- package/src/messages.ts +8 -4
- package/src/paging.ts +64 -0
- package/src/released.ts +403 -0
- package/src/reports.ts +268 -12
- package/src/reviews.ts +25 -8
- package/src/types.ts +155 -3
package/src/reports.ts
CHANGED
|
@@ -1,9 +1,15 @@
|
|
|
1
|
+
import { collect, type PageInput, type PageOf } from "./paging.js";
|
|
1
2
|
import type { HttpClient } from "./http.js";
|
|
2
3
|
import type {
|
|
3
4
|
CommentThread,
|
|
5
|
+
OpenThread,
|
|
6
|
+
OrgAnalytics,
|
|
7
|
+
ReportAnalytics,
|
|
4
8
|
PublishReportInput,
|
|
5
9
|
PublishResult,
|
|
6
10
|
ReportData,
|
|
11
|
+
ScheduleSummary,
|
|
12
|
+
SendResult,
|
|
7
13
|
UpdateReportInput,
|
|
8
14
|
EvidencePack,
|
|
9
15
|
} from "./types.js";
|
|
@@ -69,14 +75,37 @@ export class Reports {
|
|
|
69
75
|
});
|
|
70
76
|
}
|
|
71
77
|
|
|
78
|
+
/**
|
|
79
|
+
* Every report, newest change first. `query` searches title, slug and
|
|
80
|
+
* description.
|
|
81
|
+
*
|
|
82
|
+
* This one used to be the worst of them: the API had no limit at all, so an
|
|
83
|
+
* organisation past PostgREST's own cap was handed a prefix of its reports
|
|
84
|
+
* and nothing said so. It follows the cursor now, so the array really is all
|
|
85
|
+
* of them; `listPage` is there when one page is what you want.
|
|
86
|
+
*/
|
|
72
87
|
async list(query?: string, signal?: AbortSignal): Promise<ReportData[]> {
|
|
73
|
-
|
|
88
|
+
return collect(async (cursor: string | null) => {
|
|
89
|
+
const page = await this.listPage({ query, cursor: cursor ?? undefined }, signal);
|
|
90
|
+
return { items: page.items, nextCursor: page.nextCursor };
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** One page, and the cursor to continue from — null when it is the end. */
|
|
95
|
+
async listPage(
|
|
96
|
+
input: { query?: string } & PageInput = {},
|
|
97
|
+
signal?: AbortSignal
|
|
98
|
+
): Promise<PageOf<ReportData>> {
|
|
99
|
+
const { reports, nextCursor } = await this.http.request<{
|
|
100
|
+
reports: ReportData[];
|
|
101
|
+
nextCursor: string | null;
|
|
102
|
+
}>({
|
|
74
103
|
method: "GET",
|
|
75
104
|
path: "/reports",
|
|
76
|
-
query: { q: query },
|
|
105
|
+
query: { q: input.query, limit: input.limit, cursor: input.cursor },
|
|
77
106
|
signal,
|
|
78
107
|
});
|
|
79
|
-
return reports;
|
|
108
|
+
return { items: reports, nextCursor };
|
|
80
109
|
}
|
|
81
110
|
|
|
82
111
|
/** Change the title, the address, or both. The old address keeps working. */
|
|
@@ -104,7 +133,59 @@ export class Reports {
|
|
|
104
133
|
return granted;
|
|
105
134
|
}
|
|
106
135
|
|
|
107
|
-
/**
|
|
136
|
+
/**
|
|
137
|
+
* Take it away again, from the same audience phrase that granted it.
|
|
138
|
+
*
|
|
139
|
+
* By audience rather than by grant id because that is all a caller has:
|
|
140
|
+
* `get()` returns each grant's principal id, never the grant row's. Refuses
|
|
141
|
+
* when the audience never had access, so a script that revokes and carries
|
|
142
|
+
* on is not told the door is shut when it is open.
|
|
143
|
+
*/
|
|
144
|
+
async revoke(idOrSlug: string, audience: unknown, signal?: AbortSignal): Promise<unknown[]> {
|
|
145
|
+
const { revoked } = await this.http.request<{ revoked: unknown[] }>({
|
|
146
|
+
method: "DELETE",
|
|
147
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/share`,
|
|
148
|
+
body: { audience },
|
|
149
|
+
signal,
|
|
150
|
+
});
|
|
151
|
+
return revoked;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Email it to a list of addresses, inside or outside the organisation.
|
|
156
|
+
*
|
|
157
|
+
* `share` grants access to people the organisation already knows. This
|
|
158
|
+
* takes bare email addresses, creates the guest records behind them, and
|
|
159
|
+
* emails each recipient their own link with your covering note. Not a
|
|
160
|
+
* mailing list: one link per person, which is what makes the audit trail
|
|
161
|
+
* and the per-reader analytics mean anything.
|
|
162
|
+
*
|
|
163
|
+
* A publishing rule can refuse it — a report classified confidential or
|
|
164
|
+
* restricted does not leave the organisation.
|
|
165
|
+
*/
|
|
166
|
+
send(
|
|
167
|
+
idOrSlug: string,
|
|
168
|
+
input: {
|
|
169
|
+
to: string[];
|
|
170
|
+
message?: string;
|
|
171
|
+
allowComments?: boolean;
|
|
172
|
+
expiresInDays?: number;
|
|
173
|
+
},
|
|
174
|
+
signal?: AbortSignal
|
|
175
|
+
): Promise<SendResult> {
|
|
176
|
+
return this.http.request({
|
|
177
|
+
method: "POST",
|
|
178
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/send`,
|
|
179
|
+
body: input,
|
|
180
|
+
signal,
|
|
181
|
+
});
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* Stop the URL serving. A reader following a link they already hold is told
|
|
186
|
+
* the report is no longer available; nothing is deleted and the audience is
|
|
187
|
+
* kept, so `unarchive` puts it back exactly as it was.
|
|
188
|
+
*/
|
|
108
189
|
archive(idOrSlug: string, archived = true, signal?: AbortSignal): Promise<ReportData> {
|
|
109
190
|
return this.http.request({
|
|
110
191
|
method: "POST",
|
|
@@ -114,7 +195,23 @@ export class Reports {
|
|
|
114
195
|
});
|
|
115
196
|
}
|
|
116
197
|
|
|
117
|
-
|
|
198
|
+
/** Put an archived report back at the same URL, to the same audience. */
|
|
199
|
+
unarchive(idOrSlug: string, signal?: AbortSignal): Promise<ReportData> {
|
|
200
|
+
return this.archive(idOrSlug, false, signal);
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* Serve an earlier version again, at the same URL. The newer version is
|
|
205
|
+
* kept — roll forward the same way.
|
|
206
|
+
*
|
|
207
|
+
* The version number is the one `versions()` and `get()` report, not a
|
|
208
|
+
* version uuid.
|
|
209
|
+
*/
|
|
210
|
+
rollback(
|
|
211
|
+
idOrSlug: string,
|
|
212
|
+
version: number,
|
|
213
|
+
signal?: AbortSignal
|
|
214
|
+
): Promise<{ ok: true; version: number; versionId: string }> {
|
|
118
215
|
return this.http.request({
|
|
119
216
|
method: "POST",
|
|
120
217
|
path: `/reports/${encodeURIComponent(idOrSlug)}/rollback`,
|
|
@@ -136,8 +233,31 @@ export class Reports {
|
|
|
136
233
|
});
|
|
137
234
|
}
|
|
138
235
|
|
|
236
|
+
/**
|
|
237
|
+
* What is being read across every report — and what is not.
|
|
238
|
+
*
|
|
239
|
+
* `analytics` needs to be told which report, so "what is getting read" meant
|
|
240
|
+
* walking the list and adding up. The half that cannot be reconstructed that
|
|
241
|
+
* way is `inactiveReports`: a report nobody has opened does not appear in
|
|
242
|
+
* anything you would think to ask about.
|
|
243
|
+
*
|
|
244
|
+
* Part of analytics, so Team and above; `analytics` returns a total view
|
|
245
|
+
* count on every plan.
|
|
246
|
+
*/
|
|
247
|
+
orgAnalytics(
|
|
248
|
+
options: { days?: number; limit?: number } = {},
|
|
249
|
+
signal?: AbortSignal
|
|
250
|
+
): Promise<OrgAnalytics> {
|
|
251
|
+
return this.http.request({
|
|
252
|
+
method: "GET",
|
|
253
|
+
path: "/analytics",
|
|
254
|
+
query: { days: options.days, limit: options.limit },
|
|
255
|
+
signal,
|
|
256
|
+
});
|
|
257
|
+
}
|
|
258
|
+
|
|
139
259
|
/** Who read it and when. The detail needs the analytics plan. */
|
|
140
|
-
analytics(idOrSlug: string, signal?: AbortSignal): Promise<
|
|
260
|
+
analytics(idOrSlug: string, signal?: AbortSignal): Promise<ReportAnalytics> {
|
|
141
261
|
return this.http.request({
|
|
142
262
|
method: "GET",
|
|
143
263
|
path: `/reports/${encodeURIComponent(idOrSlug)}/analytics`,
|
|
@@ -168,6 +288,19 @@ export class Reports {
|
|
|
168
288
|
});
|
|
169
289
|
}
|
|
170
290
|
|
|
291
|
+
/**
|
|
292
|
+
* Remove a dataset. The published version is untouched; a report that
|
|
293
|
+
* fetches this name will show its readers an error from the next open, so
|
|
294
|
+
* `listData` first if you are not sure what reads it.
|
|
295
|
+
*/
|
|
296
|
+
deleteData(idOrSlug: string, name: string, signal?: AbortSignal): Promise<void> {
|
|
297
|
+
return this.http.request({
|
|
298
|
+
method: "DELETE",
|
|
299
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/data/${encodeURIComponent(name)}`,
|
|
300
|
+
signal,
|
|
301
|
+
});
|
|
302
|
+
}
|
|
303
|
+
|
|
171
304
|
/**
|
|
172
305
|
* The open feedback composed into one prompt, with the readers' images as
|
|
173
306
|
* signed links: everything needed to write the next version.
|
|
@@ -190,18 +323,47 @@ export class Reports {
|
|
|
190
323
|
export class Comments {
|
|
191
324
|
constructor(private readonly http: HttpClient) {}
|
|
192
325
|
|
|
326
|
+
/** Every thread on a report, newest activity first. */
|
|
193
327
|
async list(
|
|
194
328
|
idOrSlug: string,
|
|
195
329
|
status: "open" | "resolved" | "all" = "open",
|
|
196
330
|
signal?: AbortSignal
|
|
197
331
|
): Promise<CommentThread[]> {
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
332
|
+
return collect(async (cursor: string | null) => {
|
|
333
|
+
const { threads, nextCursor } = await this.http.request<{
|
|
334
|
+
threads: CommentThread[];
|
|
335
|
+
nextCursor: string | null;
|
|
336
|
+
}>({
|
|
337
|
+
method: "GET",
|
|
338
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/comments`,
|
|
339
|
+
query: { status, cursor: cursor ?? undefined },
|
|
340
|
+
signal,
|
|
341
|
+
});
|
|
342
|
+
return { items: threads, nextCursor };
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/**
|
|
347
|
+
* Every open thread in the organisation, newest activity first — the
|
|
348
|
+
* answer to "is anything waiting on me?" without naming a report first.
|
|
349
|
+
*
|
|
350
|
+
* `list` needs one, which means enumerating every report to find the two
|
|
351
|
+
* with feedback on them. Threads on archived reports are left out: the URL
|
|
352
|
+
* does not serve, so nothing can be done about them.
|
|
353
|
+
*/
|
|
354
|
+
async open(signal?: AbortSignal): Promise<OpenThread[]> {
|
|
355
|
+
return collect(async (cursor: string | null) => {
|
|
356
|
+
const { threads, nextCursor } = await this.http.request<{
|
|
357
|
+
threads: OpenThread[];
|
|
358
|
+
nextCursor: string | null;
|
|
359
|
+
}>({
|
|
360
|
+
method: "GET",
|
|
361
|
+
path: "/comments",
|
|
362
|
+
query: { cursor: cursor ?? undefined },
|
|
363
|
+
signal,
|
|
364
|
+
});
|
|
365
|
+
return { items: threads, nextCursor };
|
|
203
366
|
});
|
|
204
|
-
return threads;
|
|
205
367
|
}
|
|
206
368
|
|
|
207
369
|
/** `quote` anchors it to a passage; `threadId` replies to one. */
|
|
@@ -218,6 +380,30 @@ export class Comments {
|
|
|
218
380
|
});
|
|
219
381
|
}
|
|
220
382
|
|
|
383
|
+
/**
|
|
384
|
+
* Take back a comment you posted.
|
|
385
|
+
*
|
|
386
|
+
* Your own last comment in a thread, while the thread is open. Once
|
|
387
|
+
* somebody has replied it stays — their reply would otherwise be left
|
|
388
|
+
* answering something no longer on the page. Retracting the only comment in
|
|
389
|
+
* a thread takes the thread with it.
|
|
390
|
+
*
|
|
391
|
+
* `commentId` comes back from `create`, and `list` carries one on every
|
|
392
|
+
* message with `retractable` beside it. This closes what a reader can see
|
|
393
|
+
* and unsends nothing: the report's owner may already have been emailed.
|
|
394
|
+
*/
|
|
395
|
+
retract(
|
|
396
|
+
idOrSlug: string,
|
|
397
|
+
commentId: string,
|
|
398
|
+
signal?: AbortSignal
|
|
399
|
+
): Promise<{ status: "retracted"; threadId: string; threadRetracted: boolean }> {
|
|
400
|
+
return this.http.request({
|
|
401
|
+
method: "DELETE",
|
|
402
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/comments/${encodeURIComponent(commentId)}`,
|
|
403
|
+
signal,
|
|
404
|
+
});
|
|
405
|
+
}
|
|
406
|
+
|
|
221
407
|
/** Mark a thread resolved, with a note on what changed. */
|
|
222
408
|
resolve(
|
|
223
409
|
threadId: string,
|
|
@@ -232,3 +418,73 @@ export class Comments {
|
|
|
232
418
|
});
|
|
233
419
|
}
|
|
234
420
|
}
|
|
421
|
+
|
|
422
|
+
/**
|
|
423
|
+
* Recurring publishes.
|
|
424
|
+
*
|
|
425
|
+
* A schedule says when an agent is asked for a new version. It says nothing
|
|
426
|
+
* about who hears about one — publishing emails the report's audience either
|
|
427
|
+
* way.
|
|
428
|
+
*
|
|
429
|
+
* Read-only over the API until now, which made the timetable the one thing
|
|
430
|
+
* about an agent that could be set from the admin screen and nowhere else.
|
|
431
|
+
* An agent key cannot write here on purpose: a schedule is an instruction
|
|
432
|
+
* *to* an agent.
|
|
433
|
+
*/
|
|
434
|
+
export class Schedules {
|
|
435
|
+
constructor(private readonly http: HttpClient) {}
|
|
436
|
+
|
|
437
|
+
/** Every schedule, or only the ones waiting on a publish. */
|
|
438
|
+
async list(
|
|
439
|
+
options: { dueOnly?: boolean } = {},
|
|
440
|
+
signal?: AbortSignal
|
|
441
|
+
): Promise<ScheduleSummary[]> {
|
|
442
|
+
const { schedules } = await this.http.request<{ schedules: ScheduleSummary[] }>({
|
|
443
|
+
method: "GET",
|
|
444
|
+
path: "/schedules",
|
|
445
|
+
query: options.dueOnly ? { due: "1" } : {},
|
|
446
|
+
signal,
|
|
447
|
+
});
|
|
448
|
+
return schedules;
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
/**
|
|
452
|
+
* `recurrence` is a five-field cron expression in UTC, and it has to have a
|
|
453
|
+
* next occurrence — `0 0 30 2 *` is well-formed and never arrives, and is
|
|
454
|
+
* refused rather than stored.
|
|
455
|
+
*/
|
|
456
|
+
create(
|
|
457
|
+
input: { reportId: string; agentId: string; recurrence: string },
|
|
458
|
+
signal?: AbortSignal
|
|
459
|
+
): Promise<ScheduleSummary> {
|
|
460
|
+
return this.http.request({ method: "POST", path: "/schedules", body: input, signal });
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
/**
|
|
464
|
+
* Change the cadence, or turn it on or off.
|
|
465
|
+
*
|
|
466
|
+
* Changing the cadence re-times the next run, so moving a weekly publish
|
|
467
|
+
* from Friday to Monday does not fire once more on the Friday.
|
|
468
|
+
*/
|
|
469
|
+
update(
|
|
470
|
+
id: string,
|
|
471
|
+
input: { recurrence?: string; enabled?: boolean },
|
|
472
|
+
signal?: AbortSignal
|
|
473
|
+
): Promise<ScheduleSummary> {
|
|
474
|
+
return this.http.request({
|
|
475
|
+
method: "PATCH",
|
|
476
|
+
path: `/schedules/${encodeURIComponent(id)}`,
|
|
477
|
+
body: input,
|
|
478
|
+
signal,
|
|
479
|
+
});
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
/** Remove it. `update(id, { enabled: false })` pauses it instead. */
|
|
483
|
+
delete(id: string, signal?: AbortSignal): Promise<void> {
|
|
484
|
+
return this.http.request({
|
|
485
|
+
method: "DELETE",
|
|
486
|
+
path: `/schedules/${encodeURIComponent(id)}`,
|
|
487
|
+
signal,
|
|
488
|
+
});
|
|
489
|
+
}
|
|
490
|
+
}
|
package/src/reviews.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { listOrCollect, type PageOf } from "./paging.js";
|
|
1
2
|
import { DeliverdError, DeliverdTimeoutError } from "./errors.js";
|
|
2
3
|
import type { HttpClient } from "./http.js";
|
|
3
4
|
import { POLL_SCHEDULE } from "./approvals.js";
|
|
@@ -174,19 +175,35 @@ export class Reviews {
|
|
|
174
175
|
return new Review(this.http, data);
|
|
175
176
|
}
|
|
176
177
|
|
|
178
|
+
/**
|
|
179
|
+
* The organisation's reviews, newest first.
|
|
180
|
+
*
|
|
181
|
+
* With no `limit` this is every one of them: the API says where each page
|
|
182
|
+
* stopped and this follows the cursor to the end. With a `limit` it is one
|
|
183
|
+
* page of that size, and `listPage` hands back the cursor to continue from.
|
|
184
|
+
*/
|
|
177
185
|
async list(input: ListReviewsInput = {}, signal?: AbortSignal): Promise<Review[]> {
|
|
178
|
-
|
|
186
|
+
return listOrCollect(input, async (q: { limit?: number; cursor?: string }) => {
|
|
187
|
+
const page = await this.listPage({ ...input, ...q }, signal);
|
|
188
|
+
return { items: page.items, nextCursor: page.nextCursor };
|
|
189
|
+
});
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** One page, and the cursor to continue from — null when it is the end. */
|
|
193
|
+
async listPage(
|
|
194
|
+
input: ListReviewsInput = {},
|
|
195
|
+
signal?: AbortSignal
|
|
196
|
+
): Promise<PageOf<Review>> {
|
|
197
|
+
const { reviews, nextCursor } = await this.http.request<{
|
|
198
|
+
reviews: ReviewData[];
|
|
199
|
+
nextCursor: string | null;
|
|
200
|
+
}>({
|
|
179
201
|
method: "GET",
|
|
180
202
|
path: "/reviews",
|
|
181
|
-
query: {
|
|
182
|
-
status: input.status,
|
|
183
|
-
externalId: input.externalId,
|
|
184
|
-
reportId: input.reportId,
|
|
185
|
-
limit: input.limit,
|
|
186
|
-
},
|
|
203
|
+
query: { status: input.status, externalId: input.externalId, reportId: input.reportId, limit: input.limit, cursor: input.cursor },
|
|
187
204
|
signal,
|
|
188
205
|
});
|
|
189
|
-
return reviews.map((r) => new Review(this.http, r));
|
|
206
|
+
return { items: reviews.map((r) => new Review(this.http, r)), nextCursor };
|
|
190
207
|
}
|
|
191
208
|
|
|
192
209
|
/** Ask and wait, for the common case where there is nothing to do between. */
|
package/src/types.ts
CHANGED
|
@@ -55,7 +55,10 @@ export interface ApprovalData {
|
|
|
55
55
|
requiredApprovals: number;
|
|
56
56
|
/** How many have approved so far. Compare with `requiredApprovals`. */
|
|
57
57
|
approvalsSoFar: number;
|
|
58
|
+
/** Who decided, as a name rather than an id — the same as a review's `by`. */
|
|
58
59
|
decidedBy: string | null;
|
|
60
|
+
/** Their user id, for anything that needs the key rather than the person. */
|
|
61
|
+
decidedById: string | null;
|
|
59
62
|
decidedAt: string | null;
|
|
60
63
|
/** The approver's reason, on a rejection or an approval that carried one. */
|
|
61
64
|
note: string | null;
|
|
@@ -78,8 +81,16 @@ export interface CreateApprovalInput {
|
|
|
78
81
|
/** A published report the request is about. */
|
|
79
82
|
reportId?: string;
|
|
80
83
|
/**
|
|
81
|
-
*
|
|
82
|
-
*
|
|
84
|
+
* Who may decide. Each entry is a person — an email or a user id — or the
|
|
85
|
+
* name of a directory group or workspace, or a word meaning the whole
|
|
86
|
+
* organisation ("everyone"). Naming a team is usually what you want: a
|
|
87
|
+
* request addressed to one person waits for that person to come back from
|
|
88
|
+
* holiday, and anyone on a team can answer.
|
|
89
|
+
*
|
|
90
|
+
* The organisation's owners and admins decide when this is omitted. You
|
|
91
|
+
* cannot name only yourself; being *on* a team you address is fine and means
|
|
92
|
+
* the rest of it. A name matching both a person and a team is refused rather
|
|
93
|
+
* than guessed — name it by id.
|
|
83
94
|
*/
|
|
84
95
|
approvers?: string[];
|
|
85
96
|
/** After this the request expires undecided. ISO 8601. */
|
|
@@ -110,7 +121,10 @@ export type Decision = {
|
|
|
110
121
|
status: "approved" | "rejected" | "expired" | "cancelled";
|
|
111
122
|
/** Their reason, when they gave one. */
|
|
112
123
|
note: string | null;
|
|
124
|
+
/** Who decided, as a name rather than an id. Log it; put it in a message. */
|
|
113
125
|
decidedBy: string | null;
|
|
126
|
+
/** Their user id, when the key is what you need. */
|
|
127
|
+
decidedById: string | null;
|
|
114
128
|
decidedAt: string | null;
|
|
115
129
|
id: string;
|
|
116
130
|
/** The page they decided on. Worth logging. */
|
|
@@ -122,7 +136,10 @@ export type Decision = {
|
|
|
122
136
|
export interface ListApprovalsInput {
|
|
123
137
|
status?: ApprovalStatus;
|
|
124
138
|
externalId?: string;
|
|
139
|
+
/** One page of this size. Leave it unset to get every row. */
|
|
125
140
|
limit?: number;
|
|
141
|
+
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
142
|
+
cursor?: string;
|
|
126
143
|
}
|
|
127
144
|
|
|
128
145
|
/* ── Reports ─────────────────────────────────────────────────────────────── */
|
|
@@ -190,16 +207,141 @@ export interface PublishResult {
|
|
|
190
207
|
[key: string]: unknown;
|
|
191
208
|
}
|
|
192
209
|
|
|
210
|
+
/**
|
|
211
|
+
* One open thread, as the organisation-wide list returns it.
|
|
212
|
+
*
|
|
213
|
+
* Deliberately thinner than a `CommentThread`: this answers "where is the
|
|
214
|
+
* feedback" across every report, so it carries the report and the quoted
|
|
215
|
+
* passage rather than the whole conversation. Fetch the thread itself with
|
|
216
|
+
* `comments.list(reportId)` once you know which report to look at.
|
|
217
|
+
*/
|
|
218
|
+
export interface OpenThread {
|
|
219
|
+
threadId: string;
|
|
220
|
+
reportId: string;
|
|
221
|
+
reportTitle: string;
|
|
222
|
+
reportSlug: string;
|
|
223
|
+
/** Who owns the report — filter on it to find the threads on yours. */
|
|
224
|
+
reportOwnerId: string | null;
|
|
225
|
+
quote: string | null;
|
|
226
|
+
author: string;
|
|
227
|
+
authorType: string;
|
|
228
|
+
messages: number;
|
|
229
|
+
lastActivityAt: string;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* What a send did, per address.
|
|
234
|
+
*
|
|
235
|
+
* `delivered` is the mail provider accepting it, not the person reading it —
|
|
236
|
+
* and `alreadyHadAccess` names the recipients who could already open the
|
|
237
|
+
* report, who were emailed again anyway. Re-sending to somebody who says
|
|
238
|
+
* they never got the first one is the point.
|
|
239
|
+
*/
|
|
240
|
+
export interface SendResult {
|
|
241
|
+
sent: { email: string; delivered: boolean }[];
|
|
242
|
+
alreadyHadAccess: string[];
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/* ── Schedules ───────────────────────────────────────────────────────────── */
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* A recurring publish an agent is expected to perform.
|
|
249
|
+
*
|
|
250
|
+
* `due` is the useful field: true once the schedule has fired and nobody has
|
|
251
|
+
* acted on that firing. Publishing a new version clears it, and so does
|
|
252
|
+
* writing a dataset — for a report that reads its numbers from `_data/…`,
|
|
253
|
+
* updating the data is the whole job.
|
|
254
|
+
*/
|
|
255
|
+
export interface ScheduleSummary {
|
|
256
|
+
id: string;
|
|
257
|
+
reportId: string;
|
|
258
|
+
reportSlug: string;
|
|
259
|
+
reportTitle: string;
|
|
260
|
+
reportUrl: string;
|
|
261
|
+
agentId: string;
|
|
262
|
+
agentName: string;
|
|
263
|
+
/** Five-field cron expression, evaluated in UTC. */
|
|
264
|
+
recurrence: string;
|
|
265
|
+
enabled: boolean;
|
|
266
|
+
lastRunAt: string | null;
|
|
267
|
+
nextRunAt: string | null;
|
|
268
|
+
currentVersion: number | null;
|
|
269
|
+
due: boolean;
|
|
270
|
+
dueSince: string | null;
|
|
271
|
+
}
|
|
272
|
+
|
|
193
273
|
/* ── Comments ────────────────────────────────────────────────────────────── */
|
|
194
274
|
|
|
195
275
|
export interface CommentThread {
|
|
196
276
|
threadId: string;
|
|
197
277
|
status: "open" | "resolved";
|
|
198
278
|
quote: string | null;
|
|
199
|
-
messages: {
|
|
279
|
+
messages: {
|
|
280
|
+
/** What `comments.retract` takes. */
|
|
281
|
+
commentId: string;
|
|
282
|
+
author: string;
|
|
283
|
+
authorType: string;
|
|
284
|
+
body: string;
|
|
285
|
+
createdAt: string;
|
|
286
|
+
/** True for the one message this credential could still take back. */
|
|
287
|
+
retractable: boolean;
|
|
288
|
+
}[];
|
|
200
289
|
[key: string]: unknown;
|
|
201
290
|
}
|
|
202
291
|
|
|
292
|
+
/* ── Analytics ───────────────────────────────────────────────────────────── */
|
|
293
|
+
|
|
294
|
+
/** Who read one report. The detail beyond `totalViews` needs the analytics plan. */
|
|
295
|
+
export interface ReportAnalytics {
|
|
296
|
+
reportId: string;
|
|
297
|
+
title: string;
|
|
298
|
+
totalViews: number;
|
|
299
|
+
uniqueViewers: number | null;
|
|
300
|
+
internalViewers: number | null;
|
|
301
|
+
externalViewers: number | null;
|
|
302
|
+
firstViewedAt: string | null;
|
|
303
|
+
lastViewedAt: string | null;
|
|
304
|
+
byDay: { day: string; views: number; uniqueViewers: number }[];
|
|
305
|
+
byVersion: {
|
|
306
|
+
versionNumber: number;
|
|
307
|
+
views: number;
|
|
308
|
+
uniqueViewers: number;
|
|
309
|
+
lastViewedAt: string | null;
|
|
310
|
+
}[];
|
|
311
|
+
/** Names only where the organisation shows viewer identities. */
|
|
312
|
+
recentViewers: {
|
|
313
|
+
displayName: string;
|
|
314
|
+
principalType: string;
|
|
315
|
+
viewCount: number;
|
|
316
|
+
lastViewedAt: string;
|
|
317
|
+
}[];
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/** What is being read across every report, and what is not being read at all. */
|
|
321
|
+
export interface OrgAnalytics {
|
|
322
|
+
days: number;
|
|
323
|
+
totalViews: number;
|
|
324
|
+
uniqueViewers: number;
|
|
325
|
+
activeReports: number;
|
|
326
|
+
externallySharedReports: number;
|
|
327
|
+
publicReports: number;
|
|
328
|
+
publishesInPeriod: number;
|
|
329
|
+
topReports: {
|
|
330
|
+
reportId: string;
|
|
331
|
+
title: string;
|
|
332
|
+
views: number;
|
|
333
|
+
uniqueViewers: number;
|
|
334
|
+
lastViewedAt: string | null;
|
|
335
|
+
}[];
|
|
336
|
+
/** Live reports with no view in the period — oldest silence first. */
|
|
337
|
+
inactiveReports: {
|
|
338
|
+
reportId: string;
|
|
339
|
+
title: string;
|
|
340
|
+
lastViewedAt: string | null;
|
|
341
|
+
publishedAt: string | null;
|
|
342
|
+
}[];
|
|
343
|
+
}
|
|
344
|
+
|
|
203
345
|
/* ── Webhooks ────────────────────────────────────────────────────────────── */
|
|
204
346
|
|
|
205
347
|
export type WebhookEventName =
|
|
@@ -215,6 +357,7 @@ export type WebhookEventName =
|
|
|
215
357
|
| "approval.approved"
|
|
216
358
|
| "approval.rejected"
|
|
217
359
|
| "approval.expired"
|
|
360
|
+
| "approval.escalated"
|
|
218
361
|
| "approval.question"
|
|
219
362
|
| "approval.answered"
|
|
220
363
|
| "review.requested"
|
|
@@ -331,7 +474,10 @@ export interface ListReviewsInput {
|
|
|
331
474
|
status?: ReviewStatus;
|
|
332
475
|
externalId?: string;
|
|
333
476
|
reportId?: string;
|
|
477
|
+
/** One page of this size. Leave it unset to get every row. */
|
|
334
478
|
limit?: number;
|
|
479
|
+
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
480
|
+
cursor?: string;
|
|
335
481
|
}
|
|
336
482
|
|
|
337
483
|
/* ── Collections ──────────────────────────────────────────────────────────── */
|
|
@@ -451,7 +597,10 @@ export interface CollectedAnswers {
|
|
|
451
597
|
export interface ListCollectionsInput {
|
|
452
598
|
status?: CollectionStatus;
|
|
453
599
|
externalId?: string;
|
|
600
|
+
/** One page of this size. Leave it unset to get every row. */
|
|
454
601
|
limit?: number;
|
|
602
|
+
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
603
|
+
cursor?: string;
|
|
455
604
|
}
|
|
456
605
|
|
|
457
606
|
/* ── Flows ────────────────────────────────────────────────────────────────── */
|
|
@@ -515,7 +664,10 @@ export interface CreateFlowInput {
|
|
|
515
664
|
export interface ListFlowsInput {
|
|
516
665
|
status?: FlowStatus;
|
|
517
666
|
externalId?: string;
|
|
667
|
+
/** One page of this size. Leave it unset to get every row. */
|
|
518
668
|
limit?: number;
|
|
669
|
+
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
670
|
+
cursor?: string;
|
|
519
671
|
}
|
|
520
672
|
|
|
521
673
|
/* ── Evidence ─────────────────────────────────────────────────────────────── */
|