@deliverd/sdk 0.11.1 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/reports.ts CHANGED
@@ -1,490 +1,490 @@
1
- import { collect, type PageInput, type PageOf } from "./paging.js";
2
- import type { HttpClient } from "./http.js";
3
- import type {
4
- CommentThread,
5
- OpenThread,
6
- OrgAnalytics,
7
- ReportAnalytics,
8
- PublishReportInput,
9
- PublishResult,
10
- ReportData,
11
- ScheduleSummary,
12
- SendResult,
13
- UpdateReportInput,
14
- EvidencePack,
15
- } from "./types.js";
16
-
17
- /**
18
- * The publishing half: get what the agent wrote to the people who need it, at
19
- * an address that does not change.
20
- *
21
- * Thin on purpose. These are the REST routes with their names spelled the way
22
- * a person would say them, and nothing else — the service decides what a
23
- * publish means, and an SDK that reimplemented any of it would be a second
24
- * answer to the same question.
25
- */
26
- export class Reports {
27
- constructor(private readonly http: HttpClient) {}
28
-
29
- /**
30
- * Publish HTML to a secure URL.
31
- *
32
- * Check `result.status`: a publishing policy can hold the version for a
33
- * person's approval, in which case nothing is live yet and `result.approval`
34
- * names the request.
35
- */
36
- publish(input: PublishReportInput, signal?: AbortSignal): Promise<PublishResult> {
37
- return this.http.request({ method: "POST", path: "/reports", body: input, signal });
38
- }
39
-
40
- /** A new version of an existing report, keeping its URL and its audience. */
41
- update(
42
- idOrSlug: string,
43
- input: UpdateReportInput,
44
- signal?: AbortSignal
45
- ): Promise<PublishResult> {
46
- return this.http.request({
47
- method: "POST",
48
- path: `/reports/${encodeURIComponent(idOrSlug)}/versions`,
49
- body: input,
50
- signal,
51
- });
52
- }
53
-
54
- /**
55
- * The whole record behind a report: the approvals, reviews and requests for
56
- * information that point at it, its version history, and the timeline across
57
- * all of it.
58
- *
59
- * The subject an auditor usually names — and unlike a flow, it works for
60
- * work that was done before flows existed. Needs every read scope.
61
- */
62
- evidence(idOrSlug: string, signal?: AbortSignal): Promise<EvidencePack> {
63
- return this.http.request<EvidencePack>({
64
- method: "GET",
65
- path: `/reports/${encodeURIComponent(idOrSlug)}/evidence`,
66
- signal,
67
- });
68
- }
69
-
70
- get(idOrSlug: string, signal?: AbortSignal): Promise<ReportData> {
71
- return this.http.request({
72
- method: "GET",
73
- path: `/reports/${encodeURIComponent(idOrSlug)}`,
74
- signal,
75
- });
76
- }
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
- */
87
- async list(query?: string, signal?: AbortSignal): Promise<ReportData[]> {
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
- }>({
103
- method: "GET",
104
- path: "/reports",
105
- query: { q: input.query, limit: input.limit, cursor: input.cursor },
106
- signal,
107
- });
108
- return { items: reports, nextCursor };
109
- }
110
-
111
- /** Change the title, the address, or both. The old address keeps working. */
112
- rename(
113
- idOrSlug: string,
114
- input: { title?: string; slug?: string; description?: string; workspaceId?: string },
115
- signal?: AbortSignal
116
- ): Promise<ReportData> {
117
- return this.http.request({
118
- method: "PATCH",
119
- path: `/reports/${encodeURIComponent(idOrSlug)}`,
120
- body: input,
121
- signal,
122
- });
123
- }
124
-
125
- /** Grant people, teams or groups access. Filing is not access; this is. */
126
- async share(idOrSlug: string, audience: unknown, signal?: AbortSignal): Promise<unknown[]> {
127
- const { granted } = await this.http.request<{ granted: unknown[] }>({
128
- method: "POST",
129
- path: `/reports/${encodeURIComponent(idOrSlug)}/share`,
130
- body: { audience },
131
- signal,
132
- });
133
- return granted;
134
- }
135
-
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
- */
189
- archive(idOrSlug: string, archived = true, signal?: AbortSignal): Promise<ReportData> {
190
- return this.http.request({
191
- method: "POST",
192
- path: `/reports/${encodeURIComponent(idOrSlug)}/archive`,
193
- body: { archived },
194
- signal,
195
- });
196
- }
197
-
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 }> {
215
- return this.http.request({
216
- method: "POST",
217
- path: `/reports/${encodeURIComponent(idOrSlug)}/rollback`,
218
- body: { version },
219
- signal,
220
- });
221
- }
222
-
223
- /**
224
- * Every version, with `latestVersion` beside `currentVersion`. Pass
225
- * `latestVersion` as `expectedVersion` on an update: a held or declined
226
- * version takes a number without going live.
227
- */
228
- versions(idOrSlug: string, signal?: AbortSignal): Promise<Record<string, unknown>> {
229
- return this.http.request({
230
- method: "GET",
231
- path: `/reports/${encodeURIComponent(idOrSlug)}/versions`,
232
- signal,
233
- });
234
- }
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
-
259
- /** Who read it and when. The detail needs the analytics plan. */
260
- analytics(idOrSlug: string, signal?: AbortSignal): Promise<ReportAnalytics> {
261
- return this.http.request({
262
- method: "GET",
263
- path: `/reports/${encodeURIComponent(idOrSlug)}/analytics`,
264
- signal,
265
- });
266
- }
267
-
268
- /** Replace a dataset a living report reads. No new version, same URL. */
269
- putData(
270
- idOrSlug: string,
271
- name: string,
272
- data: unknown,
273
- signal?: AbortSignal
274
- ): Promise<unknown> {
275
- return this.http.request({
276
- method: "PUT",
277
- path: `/reports/${encodeURIComponent(idOrSlug)}/data/${encodeURIComponent(name)}`,
278
- body: data,
279
- signal,
280
- });
281
- }
282
-
283
- listData(idOrSlug: string, signal?: AbortSignal): Promise<unknown> {
284
- return this.http.request({
285
- method: "GET",
286
- path: `/reports/${encodeURIComponent(idOrSlug)}/data`,
287
- signal,
288
- });
289
- }
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
-
304
- /**
305
- * The open feedback composed into one prompt, with the readers' images as
306
- * signed links: everything needed to write the next version.
307
- */
308
- revisionBrief(
309
- idOrSlug: string,
310
- input: { threadIds?: string[]; instructions?: string } = {},
311
- signal?: AbortSignal
312
- ): Promise<Record<string, unknown>> {
313
- return this.http.request({
314
- method: "POST",
315
- path: `/reports/${encodeURIComponent(idOrSlug)}/revision-briefs`,
316
- body: input,
317
- signal,
318
- });
319
- }
320
- }
321
-
322
- /** Reader feedback, anchored to the passage it is about. */
323
- export class Comments {
324
- constructor(private readonly http: HttpClient) {}
325
-
326
- /** Every thread on a report, newest activity first. */
327
- async list(
328
- idOrSlug: string,
329
- status: "open" | "resolved" | "all" = "open",
330
- signal?: AbortSignal
331
- ): Promise<CommentThread[]> {
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 };
366
- });
367
- }
368
-
369
- /** `quote` anchors it to a passage; `threadId` replies to one. */
370
- create(
371
- idOrSlug: string,
372
- input: { body: string; quote?: string; threadId?: string },
373
- signal?: AbortSignal
374
- ): Promise<unknown> {
375
- return this.http.request({
376
- method: "POST",
377
- path: `/reports/${encodeURIComponent(idOrSlug)}/comments`,
378
- body: input,
379
- signal,
380
- });
381
- }
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
-
407
- /** Mark a thread resolved, with a note on what changed. */
408
- resolve(
409
- threadId: string,
410
- input: { note?: string; reopen?: boolean } = {},
411
- signal?: AbortSignal
412
- ): Promise<unknown> {
413
- return this.http.request({
414
- method: "POST",
415
- path: `/comments/${encodeURIComponent(threadId)}/resolve`,
416
- body: input,
417
- signal,
418
- });
419
- }
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
- }
1
+ import { collect, type PageInput, type PageOf } from "./paging.js";
2
+ import type { HttpClient } from "./http.js";
3
+ import type {
4
+ CommentThread,
5
+ OpenThread,
6
+ OrgAnalytics,
7
+ ReportAnalytics,
8
+ PublishReportInput,
9
+ PublishResult,
10
+ ReportData,
11
+ ScheduleSummary,
12
+ SendResult,
13
+ UpdateReportInput,
14
+ EvidencePack,
15
+ } from "./types.js";
16
+
17
+ /**
18
+ * The publishing half: get what the agent wrote to the people who need it, at
19
+ * an address that does not change.
20
+ *
21
+ * Thin on purpose. These are the REST routes with their names spelled the way
22
+ * a person would say them, and nothing else — the service decides what a
23
+ * publish means, and an SDK that reimplemented any of it would be a second
24
+ * answer to the same question.
25
+ */
26
+ export class Reports {
27
+ constructor(private readonly http: HttpClient) {}
28
+
29
+ /**
30
+ * Publish HTML to a secure URL.
31
+ *
32
+ * Check `result.status`: a publishing policy can hold the version for a
33
+ * person's approval, in which case nothing is live yet and `result.approval`
34
+ * names the request.
35
+ */
36
+ publish(input: PublishReportInput, signal?: AbortSignal): Promise<PublishResult> {
37
+ return this.http.request({ method: "POST", path: "/reports", body: input, signal });
38
+ }
39
+
40
+ /** A new version of an existing report, keeping its URL and its audience. */
41
+ update(
42
+ idOrSlug: string,
43
+ input: UpdateReportInput,
44
+ signal?: AbortSignal
45
+ ): Promise<PublishResult> {
46
+ return this.http.request({
47
+ method: "POST",
48
+ path: `/reports/${encodeURIComponent(idOrSlug)}/versions`,
49
+ body: input,
50
+ signal,
51
+ });
52
+ }
53
+
54
+ /**
55
+ * The whole record behind a report: the approvals, reviews and requests for
56
+ * information that point at it, its version history, and the timeline across
57
+ * all of it.
58
+ *
59
+ * The subject an auditor usually names — and unlike a flow, it works for
60
+ * work that was done before flows existed. Needs every read scope.
61
+ */
62
+ evidence(idOrSlug: string, signal?: AbortSignal): Promise<EvidencePack> {
63
+ return this.http.request<EvidencePack>({
64
+ method: "GET",
65
+ path: `/reports/${encodeURIComponent(idOrSlug)}/evidence`,
66
+ signal,
67
+ });
68
+ }
69
+
70
+ get(idOrSlug: string, signal?: AbortSignal): Promise<ReportData> {
71
+ return this.http.request({
72
+ method: "GET",
73
+ path: `/reports/${encodeURIComponent(idOrSlug)}`,
74
+ signal,
75
+ });
76
+ }
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
+ */
87
+ async list(query?: string, signal?: AbortSignal): Promise<ReportData[]> {
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
+ }>({
103
+ method: "GET",
104
+ path: "/reports",
105
+ query: { q: input.query, limit: input.limit, cursor: input.cursor },
106
+ signal,
107
+ });
108
+ return { items: reports, nextCursor };
109
+ }
110
+
111
+ /** Change the title, the address, or both. The old address keeps working. */
112
+ rename(
113
+ idOrSlug: string,
114
+ input: { title?: string; slug?: string; description?: string; workspaceId?: string },
115
+ signal?: AbortSignal
116
+ ): Promise<ReportData> {
117
+ return this.http.request({
118
+ method: "PATCH",
119
+ path: `/reports/${encodeURIComponent(idOrSlug)}`,
120
+ body: input,
121
+ signal,
122
+ });
123
+ }
124
+
125
+ /** Grant people, teams or groups access. Filing is not access; this is. */
126
+ async share(idOrSlug: string, audience: unknown, signal?: AbortSignal): Promise<unknown[]> {
127
+ const { granted } = await this.http.request<{ granted: unknown[] }>({
128
+ method: "POST",
129
+ path: `/reports/${encodeURIComponent(idOrSlug)}/share`,
130
+ body: { audience },
131
+ signal,
132
+ });
133
+ return granted;
134
+ }
135
+
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
+ */
189
+ archive(idOrSlug: string, archived = true, signal?: AbortSignal): Promise<ReportData> {
190
+ return this.http.request({
191
+ method: "POST",
192
+ path: `/reports/${encodeURIComponent(idOrSlug)}/archive`,
193
+ body: { archived },
194
+ signal,
195
+ });
196
+ }
197
+
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 }> {
215
+ return this.http.request({
216
+ method: "POST",
217
+ path: `/reports/${encodeURIComponent(idOrSlug)}/rollback`,
218
+ body: { version },
219
+ signal,
220
+ });
221
+ }
222
+
223
+ /**
224
+ * Every version, with `latestVersion` beside `currentVersion`. Pass
225
+ * `latestVersion` as `expectedVersion` on an update: a held or declined
226
+ * version takes a number without going live.
227
+ */
228
+ versions(idOrSlug: string, signal?: AbortSignal): Promise<Record<string, unknown>> {
229
+ return this.http.request({
230
+ method: "GET",
231
+ path: `/reports/${encodeURIComponent(idOrSlug)}/versions`,
232
+ signal,
233
+ });
234
+ }
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
+
259
+ /** Who read it and when. The detail needs the analytics plan. */
260
+ analytics(idOrSlug: string, signal?: AbortSignal): Promise<ReportAnalytics> {
261
+ return this.http.request({
262
+ method: "GET",
263
+ path: `/reports/${encodeURIComponent(idOrSlug)}/analytics`,
264
+ signal,
265
+ });
266
+ }
267
+
268
+ /** Replace a dataset a living report reads. No new version, same URL. */
269
+ putData(
270
+ idOrSlug: string,
271
+ name: string,
272
+ data: unknown,
273
+ signal?: AbortSignal
274
+ ): Promise<unknown> {
275
+ return this.http.request({
276
+ method: "PUT",
277
+ path: `/reports/${encodeURIComponent(idOrSlug)}/data/${encodeURIComponent(name)}`,
278
+ body: data,
279
+ signal,
280
+ });
281
+ }
282
+
283
+ listData(idOrSlug: string, signal?: AbortSignal): Promise<unknown> {
284
+ return this.http.request({
285
+ method: "GET",
286
+ path: `/reports/${encodeURIComponent(idOrSlug)}/data`,
287
+ signal,
288
+ });
289
+ }
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
+
304
+ /**
305
+ * The open feedback composed into one prompt, with the readers' images as
306
+ * signed links: everything needed to write the next version.
307
+ */
308
+ revisionBrief(
309
+ idOrSlug: string,
310
+ input: { threadIds?: string[]; instructions?: string } = {},
311
+ signal?: AbortSignal
312
+ ): Promise<Record<string, unknown>> {
313
+ return this.http.request({
314
+ method: "POST",
315
+ path: `/reports/${encodeURIComponent(idOrSlug)}/revision-briefs`,
316
+ body: input,
317
+ signal,
318
+ });
319
+ }
320
+ }
321
+
322
+ /** Reader feedback, anchored to the passage it is about. */
323
+ export class Comments {
324
+ constructor(private readonly http: HttpClient) {}
325
+
326
+ /** Every thread on a report, newest activity first. */
327
+ async list(
328
+ idOrSlug: string,
329
+ status: "open" | "resolved" | "all" = "open",
330
+ signal?: AbortSignal
331
+ ): Promise<CommentThread[]> {
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 };
366
+ });
367
+ }
368
+
369
+ /** `quote` anchors it to a passage; `threadId` replies to one. */
370
+ create(
371
+ idOrSlug: string,
372
+ input: { body: string; quote?: string; threadId?: string },
373
+ signal?: AbortSignal
374
+ ): Promise<unknown> {
375
+ return this.http.request({
376
+ method: "POST",
377
+ path: `/reports/${encodeURIComponent(idOrSlug)}/comments`,
378
+ body: input,
379
+ signal,
380
+ });
381
+ }
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
+
407
+ /** Mark a thread resolved, with a note on what changed. */
408
+ resolve(
409
+ threadId: string,
410
+ input: { note?: string; reopen?: boolean } = {},
411
+ signal?: AbortSignal
412
+ ): Promise<unknown> {
413
+ return this.http.request({
414
+ method: "POST",
415
+ path: `/comments/${encodeURIComponent(threadId)}/resolve`,
416
+ body: input,
417
+ signal,
418
+ });
419
+ }
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
+ }