@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/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
|
+
}
|