@deliverd/sdk 0.6.2 → 0.7.1

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,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
- const { reports } = await this.http.request<{ reports: 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
+ }>({
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
- /** Stop the URL serving. `archived: false` puts it back. */
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
- rollback(idOrSlug: string, version: number, signal?: AbortSignal): Promise<unknown> {
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<Record<string, unknown>> {
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
- const { threads } = await this.http.request<{ threads: CommentThread[] }>({
199
- method: "GET",
200
- path: `/reports/${encodeURIComponent(idOrSlug)}/comments`,
201
- query: { status },
202
- signal,
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
- const { reviews } = await this.http.request<{ reviews: ReviewData[] }>({
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;
@@ -118,7 +121,10 @@ export type Decision = {
118
121
  status: "approved" | "rejected" | "expired" | "cancelled";
119
122
  /** Their reason, when they gave one. */
120
123
  note: string | null;
124
+ /** Who decided, as a name rather than an id. Log it; put it in a message. */
121
125
  decidedBy: string | null;
126
+ /** Their user id, when the key is what you need. */
127
+ decidedById: string | null;
122
128
  decidedAt: string | null;
123
129
  id: string;
124
130
  /** The page they decided on. Worth logging. */
@@ -130,7 +136,10 @@ export type Decision = {
130
136
  export interface ListApprovalsInput {
131
137
  status?: ApprovalStatus;
132
138
  externalId?: string;
139
+ /** One page of this size. Leave it unset to get every row. */
133
140
  limit?: number;
141
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
142
+ cursor?: string;
134
143
  }
135
144
 
136
145
  /* ── Reports ─────────────────────────────────────────────────────────────── */
@@ -198,16 +207,141 @@ export interface PublishResult {
198
207
  [key: string]: unknown;
199
208
  }
200
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
+
201
273
  /* ── Comments ────────────────────────────────────────────────────────────── */
202
274
 
203
275
  export interface CommentThread {
204
276
  threadId: string;
205
277
  status: "open" | "resolved";
206
278
  quote: string | null;
207
- messages: { author: string; authorType: string; body: string; createdAt: string }[];
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
+ }[];
208
289
  [key: string]: unknown;
209
290
  }
210
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
+
211
345
  /* ── Webhooks ────────────────────────────────────────────────────────────── */
212
346
 
213
347
  export type WebhookEventName =
@@ -223,6 +357,7 @@ export type WebhookEventName =
223
357
  | "approval.approved"
224
358
  | "approval.rejected"
225
359
  | "approval.expired"
360
+ | "approval.escalated"
226
361
  | "approval.question"
227
362
  | "approval.answered"
228
363
  | "review.requested"
@@ -339,7 +474,10 @@ export interface ListReviewsInput {
339
474
  status?: ReviewStatus;
340
475
  externalId?: string;
341
476
  reportId?: string;
477
+ /** One page of this size. Leave it unset to get every row. */
342
478
  limit?: number;
479
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
480
+ cursor?: string;
343
481
  }
344
482
 
345
483
  /* ── Collections ──────────────────────────────────────────────────────────── */
@@ -459,7 +597,10 @@ export interface CollectedAnswers {
459
597
  export interface ListCollectionsInput {
460
598
  status?: CollectionStatus;
461
599
  externalId?: string;
600
+ /** One page of this size. Leave it unset to get every row. */
462
601
  limit?: number;
602
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
603
+ cursor?: string;
463
604
  }
464
605
 
465
606
  /* ── Flows ────────────────────────────────────────────────────────────────── */
@@ -523,7 +664,10 @@ export interface CreateFlowInput {
523
664
  export interface ListFlowsInput {
524
665
  status?: FlowStatus;
525
666
  externalId?: string;
667
+ /** One page of this size. Leave it unset to get every row. */
526
668
  limit?: number;
669
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
670
+ cursor?: string;
527
671
  }
528
672
 
529
673
  /* ── Evidence ─────────────────────────────────────────────────────────────── */