@deliverd/sdk 0.1.0 → 0.3.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/reviews.ts ADDED
@@ -0,0 +1,208 @@
1
+ import { DeliverdError, DeliverdTimeoutError } from "./errors.js";
2
+ import type { HttpClient } from "./http.js";
3
+ import { POLL_SCHEDULE } from "./approvals.js";
4
+ import type {
5
+ CreateReviewInput,
6
+ ListReviewsInput,
7
+ ReviewData,
8
+ ReviewOutcome,
9
+ } from "./types.js";
10
+
11
+ /**
12
+ * Ask people to read what you made and say whether it is right.
13
+ *
14
+ * The sibling of approvals, and the difference is worth keeping straight: an
15
+ * approval asks permission for something that has not happened, a review asks
16
+ * judgement on something that has. The waiting is the same shape, so the
17
+ * polling is shared.
18
+ */
19
+
20
+ export interface ReviewWaitOptions {
21
+ /** Called after every poll, for a progress line in a CLI. */
22
+ onPoll?: (review: ReviewData) => void;
23
+ /**
24
+ * Give up after this many milliseconds and throw `DeliverdTimeoutError`.
25
+ * Omitted, the wait ends when the review does — which, for a review with no
26
+ * `expiresAt`, may be never. Set one or the other.
27
+ */
28
+ timeout?: number;
29
+ signal?: AbortSignal;
30
+ /** How long between polls, as the wait lengthens. Rarely worth changing. */
31
+ pollIntervals?: readonly number[];
32
+ }
33
+
34
+ function pollDelay(poll: number, schedule: readonly number[]): number {
35
+ const base = schedule[Math.min(poll, schedule.length - 1)] ?? 60_000;
36
+ // Jitter, so a hundred agents started by the same cron do not arrive together.
37
+ return base * 0.75 + Math.random() * base * 0.5;
38
+ }
39
+
40
+ /** A review, and what you can do with it. */
41
+ export class Review {
42
+ constructor(
43
+ private readonly http: HttpClient,
44
+ private data: ReviewData
45
+ ) {}
46
+
47
+ get id(): string { return this.data.id; }
48
+ get status(): ReviewData["status"] { return this.data.status; }
49
+ /** The page the reviewer reads and decides on. */
50
+ get url(): string { return this.data.url; }
51
+ get title(): string { return this.data.title; }
52
+ get verdicts(): ReviewData["verdicts"] { return this.data.verdicts; }
53
+ /** How many comment threads the reviewers opened while reading. */
54
+ get threadCount(): number { return this.data.threadCount; }
55
+
56
+ /** The one to branch on. False for changes requested, expired and cancelled. */
57
+ get approved(): boolean { return this.data.status === "approved"; }
58
+ get changesRequested(): boolean { return this.data.status === "changes_requested"; }
59
+ get expired(): boolean { return this.data.status === "expired"; }
60
+ get cancelled(): boolean { return this.data.status === "cancelled"; }
61
+ get pending(): boolean { return this.data.status === "pending"; }
62
+
63
+ /** Everything the API returned, if you want a field the getters do not name. */
64
+ toJSON(): ReviewData { return this.data; }
65
+
66
+ toOutcome(): ReviewOutcome {
67
+ const status = this.data.status === "pending" ? "expired" : this.data.status;
68
+ return {
69
+ approved: this.data.status === "approved",
70
+ status,
71
+ verdicts: this.data.verdicts,
72
+ threadCount: this.data.threadCount,
73
+ id: this.data.id,
74
+ url: this.data.url,
75
+ review: this.data,
76
+ } as ReviewOutcome;
77
+ }
78
+
79
+ async refresh(signal?: AbortSignal): Promise<this> {
80
+ this.data = await this.http.request<ReviewData>({
81
+ method: "GET",
82
+ path: `/reviews/${this.data.id}`,
83
+ signal,
84
+ });
85
+ return this;
86
+ }
87
+
88
+ /** Withdraw it. The row stays as evidence of what was asked and dropped. */
89
+ async cancel(signal?: AbortSignal): Promise<this> {
90
+ this.data = await this.http.request<ReviewData>({
91
+ method: "POST",
92
+ path: `/reviews/${this.data.id}/cancel`,
93
+ signal,
94
+ });
95
+ return this;
96
+ }
97
+
98
+ /**
99
+ * Block until the reviewers settle it, then return.
100
+ *
101
+ * Resolves on every ending, including changes requested — that is an answer
102
+ * and the most useful one, because it comes with the threads that say what
103
+ * to change. It throws only when the wait itself failed: a timeout, an
104
+ * abort, or an API that could not be reached.
105
+ */
106
+ async wait(options: ReviewWaitOptions = {}): Promise<this> {
107
+ const deadline = options.timeout !== undefined ? Date.now() + options.timeout : undefined;
108
+ let poll = 0;
109
+ if (!this.pending) return this;
110
+
111
+ for (;;) {
112
+ if (options.signal?.aborted) {
113
+ throw new DeliverdError(0, "aborted", "The wait was aborted.", undefined, {
114
+ cause: options.signal.reason,
115
+ });
116
+ }
117
+ if (deadline !== undefined && Date.now() >= deadline) {
118
+ throw new DeliverdTimeoutError(
119
+ `Nobody finished reviewing "${this.data.title}" within the timeout. It is still open at ${this.data.url}.`
120
+ );
121
+ }
122
+ const delay = pollDelay(poll++, options.pollIntervals ?? POLL_SCHEDULE);
123
+ const remaining = deadline === undefined ? delay : Math.min(delay, deadline - Date.now());
124
+ await sleep(Math.max(0, remaining), options.signal);
125
+
126
+ await this.refresh(options.signal);
127
+ options.onPoll?.(this.data);
128
+ if (!this.pending) return this;
129
+ }
130
+ }
131
+ }
132
+
133
+ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
134
+ return new Promise((resolve, reject) => {
135
+ if (signal?.aborted) {
136
+ return reject(new DeliverdError(0, "aborted", "The wait was aborted."));
137
+ }
138
+ const timer = setTimeout(() => {
139
+ signal?.removeEventListener("abort", onAbort);
140
+ resolve();
141
+ }, ms);
142
+ const onAbort = () => {
143
+ clearTimeout(timer);
144
+ reject(new DeliverdError(0, "aborted", "The wait was aborted."));
145
+ };
146
+ signal?.addEventListener("abort", onAbort, { once: true });
147
+ });
148
+ }
149
+
150
+ export class Reviews {
151
+ constructor(private readonly http: HttpClient) {}
152
+
153
+ /**
154
+ * Ask. Returns as soon as the request is filed — the reviewers are being
155
+ * told while this resolves — so call `wait()` next, or keep the id and poll
156
+ * later.
157
+ */
158
+ async create(input: CreateReviewInput, signal?: AbortSignal): Promise<Review> {
159
+ const data = await this.http.request<ReviewData>({
160
+ method: "POST",
161
+ path: "/reviews",
162
+ body: input,
163
+ signal,
164
+ });
165
+ return new Review(this.http, data);
166
+ }
167
+
168
+ async get(id: string, signal?: AbortSignal): Promise<Review> {
169
+ const data = await this.http.request<ReviewData>({
170
+ method: "GET",
171
+ path: `/reviews/${id}`,
172
+ signal,
173
+ });
174
+ return new Review(this.http, data);
175
+ }
176
+
177
+ async list(input: ListReviewsInput = {}, signal?: AbortSignal): Promise<Review[]> {
178
+ const { reviews } = await this.http.request<{ reviews: ReviewData[] }>({
179
+ method: "GET",
180
+ path: "/reviews",
181
+ query: {
182
+ status: input.status,
183
+ externalId: input.externalId,
184
+ reportId: input.reportId,
185
+ limit: input.limit,
186
+ },
187
+ signal,
188
+ });
189
+ return reviews.map((r) => new Review(this.http, r));
190
+ }
191
+
192
+ /** Ask and wait, for the common case where there is nothing to do between. */
193
+ async request(input: CreateReviewInput, options: ReviewWaitOptions = {}): Promise<Review> {
194
+ const review = await this.create(input, options.signal);
195
+ return review.wait(options);
196
+ }
197
+
198
+ /**
199
+ * The same request as before, when there was one — so restarting a crashed
200
+ * agent does not ask the same people twice. The caveat is the one
201
+ * `approvals.findByExternalId` carries: two concurrent calls can still both
202
+ * find nothing and both create.
203
+ */
204
+ async findByExternalId(externalId: string, signal?: AbortSignal): Promise<Review | null> {
205
+ const found = await this.list({ externalId, limit: 1 }, signal);
206
+ return found[0] ?? null;
207
+ }
208
+ }
package/src/types.ts CHANGED
@@ -202,7 +202,12 @@ export type WebhookEventName =
202
202
  | "approval.rejected"
203
203
  | "approval.expired"
204
204
  | "approval.question"
205
- | "approval.answered";
205
+ | "approval.answered"
206
+ | "review.requested"
207
+ | "review.approved"
208
+ | "review.changes_requested"
209
+ | "collection.requested"
210
+ | "collection.completed";
206
211
 
207
212
  export interface WebhookEvent {
208
213
  event: WebhookEventName;
@@ -211,3 +216,213 @@ export interface WebhookEvent {
211
216
  test?: boolean;
212
217
  data: Record<string, unknown>;
213
218
  }
219
+
220
+ /* ── Reviews ──────────────────────────────────────────────────────────────── */
221
+
222
+ export type ReviewStatus =
223
+ | "pending"
224
+ | "approved"
225
+ | "changes_requested"
226
+ | "expired"
227
+ | "cancelled";
228
+
229
+ export interface CreateReviewInput {
230
+ /** What is being reviewed, as a headline the reviewer sees first. */
231
+ title: string;
232
+ /**
233
+ * What to check. Without this a reviewer decides what "review" means, and
234
+ * usually decides it means "looks fine".
235
+ */
236
+ instructions?: string;
237
+ /** The published report under review; the reviewer reads it and comments on it. */
238
+ reportId?: string;
239
+ /** Pin a version, so publishing again mid-review does not move the ground. */
240
+ versionId?: string;
241
+ /**
242
+ * Emails or user ids. An active member, or a guest who can already open the
243
+ * report — anyone else is refused rather than emailed. You cannot name
244
+ * yourself.
245
+ */
246
+ reviewers: string[];
247
+ /**
248
+ * How many approvals settle it; one when omitted. A single "changes
249
+ * requested" settles it regardless.
250
+ */
251
+ requiredApprovals?: number;
252
+ /** After this the review expires unanswered. ISO 8601. */
253
+ expiresAt?: string;
254
+ /** Your own reference, returned unchanged and searchable. */
255
+ externalId?: string;
256
+ metadata?: Record<string, unknown>;
257
+ }
258
+
259
+ export interface ReviewerRef {
260
+ kind: "user" | "guest";
261
+ id: string;
262
+ label: string;
263
+ }
264
+
265
+ export interface ReviewVerdict {
266
+ verdict: "approved" | "changes_requested";
267
+ /** Who gave it, as a name rather than an id. */
268
+ by: string;
269
+ note: string | null;
270
+ at: string;
271
+ }
272
+
273
+ export interface ReviewData {
274
+ id: string;
275
+ status: ReviewStatus;
276
+ /** The page the reviewer reads and decides on. */
277
+ url: string;
278
+ title: string;
279
+ instructions: string | null;
280
+ reportId: string | null;
281
+ versionId: string | null;
282
+ externalId: string | null;
283
+ metadata: Record<string, unknown>;
284
+ requestedBy: string;
285
+ requiredApprovals: number;
286
+ reviewers: ReviewerRef[];
287
+ verdicts: ReviewVerdict[];
288
+ /** How many comment threads the reviewers opened while reading. */
289
+ threadCount: number;
290
+ settledAt: string | null;
291
+ expiresAt: string | null;
292
+ createdAt: string;
293
+ }
294
+
295
+ /** The answer, flattened — what `review()` hands back. */
296
+ export interface ReviewOutcome {
297
+ /** The one to branch on. False for changes requested, expired and cancelled. */
298
+ approved: boolean;
299
+ status: Exclude<ReviewStatus, "pending">;
300
+ /** Every verdict returned, in the order they arrived. */
301
+ verdicts: ReviewVerdict[];
302
+ /** How many comment threads to read before producing the next version. */
303
+ threadCount: number;
304
+ id: string;
305
+ url: string;
306
+ review: ReviewData;
307
+ }
308
+
309
+ export interface ListReviewsInput {
310
+ status?: ReviewStatus;
311
+ externalId?: string;
312
+ reportId?: string;
313
+ limit?: number;
314
+ }
315
+
316
+ /* ── Collections ──────────────────────────────────────────────────────────── */
317
+
318
+ export type CollectionStatus = "pending" | "complete" | "expired" | "cancelled";
319
+
320
+ export type QuestionKind =
321
+ | "text"
322
+ | "long_text"
323
+ | "number"
324
+ | "date"
325
+ | "choice"
326
+ | "multi_choice"
327
+ | "boolean";
328
+
329
+ /** What an answer can hold, shaped by its question's kind. */
330
+ export type AnswerValue = string | number | boolean | string[];
331
+
332
+ export interface QuestionInput {
333
+ /** The question, as you would ask it out loud. */
334
+ prompt: string;
335
+ /** The sentence under the field that stops the wrong answer being given. */
336
+ help?: string;
337
+ kind: QuestionKind;
338
+ /** Required unless you say otherwise; a required question blocks submission. */
339
+ required?: boolean;
340
+ /** For `choice` and `multi_choice`. At least two, or it is not a question. */
341
+ options?: string[];
342
+ }
343
+
344
+ export interface CreateCollectionInput {
345
+ /** What you need, as a headline the person sees first. */
346
+ title: string;
347
+ /** Why you are asking, shown above the questions. */
348
+ instructions?: string;
349
+ questions: QuestionInput[];
350
+ /**
351
+ * Emails or user ids. An active member, or a guest the organisation already
352
+ * knows — anyone else is refused rather than emailed.
353
+ */
354
+ respondents: string[];
355
+ /** How many submitted replies complete it; everyone asked, when omitted. */
356
+ requiredResponses?: number;
357
+ /** A published report the request is about. */
358
+ reportId?: string;
359
+ /** Shown to the person, and what the single reminder is measured against. */
360
+ dueAt?: string;
361
+ /** After this the request closes unanswered. ISO 8601. */
362
+ expiresAt?: string;
363
+ externalId?: string;
364
+ metadata?: Record<string, unknown>;
365
+ }
366
+
367
+ export interface CollectionQuestion {
368
+ id: string;
369
+ prompt: string;
370
+ help: string | null;
371
+ kind: QuestionKind;
372
+ required: boolean;
373
+ options: string[];
374
+ }
375
+
376
+ export interface CollectionReply {
377
+ /** Who answered, as a name rather than an id. */
378
+ respondent: string;
379
+ status: "pending" | "submitted";
380
+ submittedAt: string | null;
381
+ /** Empty until they submit: a half-typed draft is not what they meant to say. */
382
+ answers: { question: string; kind: QuestionKind; value: AnswerValue }[];
383
+ }
384
+
385
+ export interface CollectionData {
386
+ id: string;
387
+ status: CollectionStatus;
388
+ /** The page the person fills in. */
389
+ url: string;
390
+ title: string;
391
+ instructions: string | null;
392
+ reportId: string | null;
393
+ externalId: string | null;
394
+ metadata: Record<string, unknown>;
395
+ requestedBy: string;
396
+ requiredResponses: number;
397
+ questions: CollectionQuestion[];
398
+ responses: CollectionReply[];
399
+ submittedCount: number;
400
+ askedCount: number;
401
+ settledAt: string | null;
402
+ dueAt: string | null;
403
+ expiresAt: string | null;
404
+ createdAt: string;
405
+ }
406
+
407
+ /** The answers, flattened — what `collect()` hands back. */
408
+ export interface CollectedAnswers {
409
+ /** True when enough people replied; false if it expired or was withdrawn. */
410
+ complete: boolean;
411
+ status: Exclude<CollectionStatus, "pending">;
412
+ /** Every submitted reply, in the order they arrived. */
413
+ responses: CollectionReply[];
414
+ /**
415
+ * The first submitted answer to each question, by its prompt — the shape
416
+ * most callers want when they asked one person for three facts.
417
+ */
418
+ answers: Record<string, AnswerValue>;
419
+ id: string;
420
+ url: string;
421
+ collection: CollectionData;
422
+ }
423
+
424
+ export interface ListCollectionsInput {
425
+ status?: CollectionStatus;
426
+ externalId?: string;
427
+ limit?: number;
428
+ }