@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/README.md +106 -10
- package/dist/collections.d.ts +78 -0
- package/dist/collections.d.ts.map +1 -0
- package/dist/collections.js +170 -0
- package/dist/dev.d.ts +1 -1
- package/dist/dev.d.ts.map +1 -1
- package/dist/dev.js +238 -2
- package/dist/index.d.ts +86 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +107 -0
- package/dist/reviews.d.ts +80 -0
- package/dist/reviews.d.ts.map +1 -0
- package/dist/reviews.js +165 -0
- package/dist/types.d.ts +182 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/collections.ts +214 -0
- package/src/dev.ts +275 -3
- package/src/index.ts +161 -0
- package/src/reviews.ts +208 -0
- package/src/types.ts +216 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,12 +1,16 @@
|
|
|
1
1
|
import { HttpClient, type ClientOptions } from "./http.js";
|
|
2
2
|
import { Approvals, type WaitOptions } from "./approvals.js";
|
|
3
3
|
import { Comments, Reports } from "./reports.js";
|
|
4
|
+
import { Reviews, type ReviewWaitOptions } from "./reviews.js";
|
|
5
|
+
import { Collections, type CollectWaitOptions } from "./collections.js";
|
|
4
6
|
import { Webhooks } from "./webhooks.js";
|
|
5
7
|
import { type DevelopmentOptions } from "./dev.js";
|
|
6
8
|
import { type Duration } from "./duration.js";
|
|
7
|
-
import type { CreateApprovalInput, Decision, PublishReportInput, PublishResult } from "./types.js";
|
|
9
|
+
import type { CollectedAnswers, CreateApprovalInput, CreateCollectionInput, CreateReviewInput, Decision, PublishReportInput, PublishResult, ReviewOutcome } from "./types.js";
|
|
8
10
|
export { Approval, Approvals, POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
|
|
9
11
|
export { Comments, Reports } from "./reports.js";
|
|
12
|
+
export { Review, Reviews, type ReviewWaitOptions } from "./reviews.js";
|
|
13
|
+
export { Collection, Collections, type CollectWaitOptions } from "./collections.js";
|
|
10
14
|
export { constructEvent, DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER, TOLERANCE_SECONDS, verifySignature, Webhooks, } from "./webhooks.js";
|
|
11
15
|
export { DeliverdError, DeliverdTimeoutError } from "./errors.js";
|
|
12
16
|
export { DEFAULT_BASE_URL, type ClientOptions } from "./http.js";
|
|
@@ -47,6 +51,40 @@ export interface ApproveOptions extends Omit<CreateApprovalInput, "expiresAt"> {
|
|
|
47
51
|
*/
|
|
48
52
|
reuse?: boolean;
|
|
49
53
|
}
|
|
54
|
+
/** Everything `review()` takes, plus the conveniences it adds on top. */
|
|
55
|
+
export interface ReviewOptions extends Omit<CreateReviewInput, "expiresAt"> {
|
|
56
|
+
/** `"4h"`, `"30m"`, `"2d"`, or milliseconds. Default 24 hours. */
|
|
57
|
+
expiresIn?: Duration;
|
|
58
|
+
/** An exact moment instead, if you have one. */
|
|
59
|
+
expiresAt?: string;
|
|
60
|
+
/** Called after each poll — a progress line in a CLI. */
|
|
61
|
+
onPoll?: ReviewWaitOptions["onPoll"];
|
|
62
|
+
/** Give up waiting after this. The review stays open until it expires. */
|
|
63
|
+
timeout?: Duration;
|
|
64
|
+
signal?: AbortSignal;
|
|
65
|
+
/**
|
|
66
|
+
* With an `externalId`, reuse an existing review rather than filing a
|
|
67
|
+
* second one, so a restarted agent does not ask the same people twice.
|
|
68
|
+
*/
|
|
69
|
+
reuse?: boolean;
|
|
70
|
+
}
|
|
71
|
+
/** Everything `collect()` takes, plus the conveniences it adds on top. */
|
|
72
|
+
export interface CollectOptions extends Omit<CreateCollectionInput, "expiresAt"> {
|
|
73
|
+
/** `"4h"`, `"30m"`, `"2d"`, or milliseconds. Default 24 hours. */
|
|
74
|
+
expiresIn?: Duration;
|
|
75
|
+
/** An exact moment instead, if you have one. */
|
|
76
|
+
expiresAt?: string;
|
|
77
|
+
/** Called after each poll — a progress line in a CLI. */
|
|
78
|
+
onPoll?: CollectWaitOptions["onPoll"];
|
|
79
|
+
/** Give up waiting after this. The request stays open until it expires. */
|
|
80
|
+
timeout?: Duration;
|
|
81
|
+
signal?: AbortSignal;
|
|
82
|
+
/**
|
|
83
|
+
* With an `externalId`, reuse an existing request rather than filing a
|
|
84
|
+
* second one, so a restarted agent does not ask the same people twice.
|
|
85
|
+
*/
|
|
86
|
+
reuse?: boolean;
|
|
87
|
+
}
|
|
50
88
|
/**
|
|
51
89
|
* Deliverd: you build the action, Deliverd handles the human.
|
|
52
90
|
*
|
|
@@ -68,6 +106,8 @@ export interface ApproveOptions extends Omit<CreateApprovalInput, "expiresAt"> {
|
|
|
68
106
|
*/
|
|
69
107
|
export declare class Deliverd {
|
|
70
108
|
readonly approvals: Approvals;
|
|
109
|
+
readonly reviews: Reviews;
|
|
110
|
+
readonly collections: Collections;
|
|
71
111
|
readonly reports: Reports;
|
|
72
112
|
readonly comments: Comments;
|
|
73
113
|
readonly webhooks: Webhooks;
|
|
@@ -95,6 +135,51 @@ export declare class Deliverd {
|
|
|
95
135
|
* `approve()`.
|
|
96
136
|
*/
|
|
97
137
|
confirm(options: ApproveOptions): Promise<boolean>;
|
|
138
|
+
/**
|
|
139
|
+
* Ask people to read what you made, and wait for their answer.
|
|
140
|
+
*
|
|
141
|
+
* The other half of judgement. `approve()` asks permission before you act;
|
|
142
|
+
* this asks whether what you already produced is right, and comes back with
|
|
143
|
+
* the reviewers' verdicts and a count of the comment threads they opened.
|
|
144
|
+
*
|
|
145
|
+
* ```ts
|
|
146
|
+
* const outcome = await deliverd.review({
|
|
147
|
+
* title: "Q3 board pack",
|
|
148
|
+
* reportId: report.id,
|
|
149
|
+
* instructions: "Check the figures against the ledger.",
|
|
150
|
+
* reviewers: ["partner@firm.example"],
|
|
151
|
+
* });
|
|
152
|
+
* if (!outcome.approved) await revise(outcome.verdicts);
|
|
153
|
+
* ```
|
|
154
|
+
*
|
|
155
|
+
* Resolves on changes requested as well as approval, because that is an
|
|
156
|
+
* answer — usually the more useful one. Reviews expire after a day unless
|
|
157
|
+
* you say otherwise, so a wait always ends.
|
|
158
|
+
*/
|
|
159
|
+
review(options: ReviewOptions): Promise<ReviewOutcome>;
|
|
160
|
+
/**
|
|
161
|
+
* Ask people for what you do not have, and wait for it.
|
|
162
|
+
*
|
|
163
|
+
* `approve()` asks permission, `review()` asks judgement, and this asks for
|
|
164
|
+
* a fact — a figure, a date, a choice between options, the sentence only
|
|
165
|
+
* they can write.
|
|
166
|
+
*
|
|
167
|
+
* ```ts
|
|
168
|
+
* const { answers } = await deliverd.collect({
|
|
169
|
+
* title: "Before I file the Q3 return",
|
|
170
|
+
* respondents: ["finance@firm.example"],
|
|
171
|
+
* questions: [
|
|
172
|
+
* { prompt: "Headcount at 30 September", kind: "number" },
|
|
173
|
+
* { prompt: "Any disposals in the quarter?", kind: "boolean" },
|
|
174
|
+
* ],
|
|
175
|
+
* });
|
|
176
|
+
* ```
|
|
177
|
+
*
|
|
178
|
+
* `answers` is keyed by the question you asked. Check `complete` before you
|
|
179
|
+
* use it: a request that expired has whatever arrived and no more, and the
|
|
180
|
+
* thing you do without the figure is usually not the thing you do with it.
|
|
181
|
+
*/
|
|
182
|
+
collect(options: CollectOptions): Promise<CollectedAnswers>;
|
|
98
183
|
/** Publish HTML to a secure URL. The other half of the product, one call in. */
|
|
99
184
|
publish(input: PublishReportInput, signal?: AbortSignal): Promise<PublishResult>;
|
|
100
185
|
}
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAsB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,KAAK,EACV,mBAAmB,EACnB,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,cAAc,EACd,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC1D,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACvE,mBAAmB,YAAY,CAAC;AAEhC,+EAA+E;AAC/E,eAAO,MAAM,cAAc,EAAE,QAAgB,CAAC;AAE9C,MAAM,WAAW,eAAgB,SAAQ,OAAO,CAAC,aAAa,CAAC;IAC7D;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC;IAC5E,kEAAkE;IAClE,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IACvC,yDAAyD;IACzD,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC/B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAElB,OAAO,GAAE,eAAoB;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/index.js
CHANGED
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
import { HttpClient } from "./http.js";
|
|
2
2
|
import { Approvals, FAST_POLL_SCHEDULE } from "./approvals.js";
|
|
3
3
|
import { Comments, Reports } from "./reports.js";
|
|
4
|
+
import { Reviews } from "./reviews.js";
|
|
5
|
+
import { Collections } from "./collections.js";
|
|
4
6
|
import { Webhooks } from "./webhooks.js";
|
|
5
7
|
import { developmentFetch } from "./dev.js";
|
|
6
8
|
import { durationMs } from "./duration.js";
|
|
7
9
|
export { Approval, Approvals, POLL_SCHEDULE } from "./approvals.js";
|
|
8
10
|
export { Comments, Reports } from "./reports.js";
|
|
11
|
+
export { Review, Reviews } from "./reviews.js";
|
|
12
|
+
export { Collection, Collections } from "./collections.js";
|
|
9
13
|
export { constructEvent, DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER, TOLERANCE_SECONDS, verifySignature, Webhooks, } from "./webhooks.js";
|
|
10
14
|
export { DeliverdError, DeliverdTimeoutError } from "./errors.js";
|
|
11
15
|
export { DEFAULT_BASE_URL } from "./http.js";
|
|
@@ -33,6 +37,8 @@ export const DEFAULT_EXPIRY = "24h";
|
|
|
33
37
|
*/
|
|
34
38
|
export class Deliverd {
|
|
35
39
|
approvals;
|
|
40
|
+
reviews;
|
|
41
|
+
collections;
|
|
36
42
|
reports;
|
|
37
43
|
comments;
|
|
38
44
|
webhooks;
|
|
@@ -50,6 +56,8 @@ export class Deliverd {
|
|
|
50
56
|
fetch: this.development ? developmentFetch(options.development) : options.fetch,
|
|
51
57
|
});
|
|
52
58
|
this.approvals = new Approvals(this.http);
|
|
59
|
+
this.reviews = new Reviews(this.http);
|
|
60
|
+
this.collections = new Collections(this.http);
|
|
53
61
|
this.reports = new Reports(this.http);
|
|
54
62
|
this.comments = new Comments(this.http);
|
|
55
63
|
this.webhooks = new Webhooks();
|
|
@@ -112,6 +120,105 @@ export class Deliverd {
|
|
|
112
120
|
const decision = await this.approve({ risk: "low", expiresIn: "1h", ...options });
|
|
113
121
|
return decision.approved;
|
|
114
122
|
}
|
|
123
|
+
/**
|
|
124
|
+
* Ask people to read what you made, and wait for their answer.
|
|
125
|
+
*
|
|
126
|
+
* The other half of judgement. `approve()` asks permission before you act;
|
|
127
|
+
* this asks whether what you already produced is right, and comes back with
|
|
128
|
+
* the reviewers' verdicts and a count of the comment threads they opened.
|
|
129
|
+
*
|
|
130
|
+
* ```ts
|
|
131
|
+
* const outcome = await deliverd.review({
|
|
132
|
+
* title: "Q3 board pack",
|
|
133
|
+
* reportId: report.id,
|
|
134
|
+
* instructions: "Check the figures against the ledger.",
|
|
135
|
+
* reviewers: ["partner@firm.example"],
|
|
136
|
+
* });
|
|
137
|
+
* if (!outcome.approved) await revise(outcome.verdicts);
|
|
138
|
+
* ```
|
|
139
|
+
*
|
|
140
|
+
* Resolves on changes requested as well as approval, because that is an
|
|
141
|
+
* answer — usually the more useful one. Reviews expire after a day unless
|
|
142
|
+
* you say otherwise, so a wait always ends.
|
|
143
|
+
*/
|
|
144
|
+
async review(options) {
|
|
145
|
+
const { expiresIn, timeout, onPoll, signal, reuse, ...input } = options;
|
|
146
|
+
if (input.externalId && reuse !== false) {
|
|
147
|
+
const existing = await this.reviews.findByExternalId(input.externalId, signal);
|
|
148
|
+
if (existing) {
|
|
149
|
+
const settled = await existing.wait({
|
|
150
|
+
onPoll,
|
|
151
|
+
signal,
|
|
152
|
+
timeout: durationOrUndefined(timeout),
|
|
153
|
+
...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
|
|
154
|
+
});
|
|
155
|
+
return settled.toOutcome();
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
const review = await this.reviews.create({
|
|
159
|
+
...input,
|
|
160
|
+
expiresAt: options.expiresAt ??
|
|
161
|
+
new Date(Date.now() + durationMs(expiresIn ?? DEFAULT_EXPIRY)).toISOString(),
|
|
162
|
+
}, signal);
|
|
163
|
+
const settled = await review.wait({
|
|
164
|
+
onPoll,
|
|
165
|
+
signal,
|
|
166
|
+
// Same reasoning as approve(): in development the reviewer is imaginary
|
|
167
|
+
// and instant, so a wait still running after a moment will never settle.
|
|
168
|
+
timeout: durationOrUndefined(timeout) ?? (this.development ? 2_000 : undefined),
|
|
169
|
+
...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
|
|
170
|
+
});
|
|
171
|
+
return settled.toOutcome();
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Ask people for what you do not have, and wait for it.
|
|
175
|
+
*
|
|
176
|
+
* `approve()` asks permission, `review()` asks judgement, and this asks for
|
|
177
|
+
* a fact — a figure, a date, a choice between options, the sentence only
|
|
178
|
+
* they can write.
|
|
179
|
+
*
|
|
180
|
+
* ```ts
|
|
181
|
+
* const { answers } = await deliverd.collect({
|
|
182
|
+
* title: "Before I file the Q3 return",
|
|
183
|
+
* respondents: ["finance@firm.example"],
|
|
184
|
+
* questions: [
|
|
185
|
+
* { prompt: "Headcount at 30 September", kind: "number" },
|
|
186
|
+
* { prompt: "Any disposals in the quarter?", kind: "boolean" },
|
|
187
|
+
* ],
|
|
188
|
+
* });
|
|
189
|
+
* ```
|
|
190
|
+
*
|
|
191
|
+
* `answers` is keyed by the question you asked. Check `complete` before you
|
|
192
|
+
* use it: a request that expired has whatever arrived and no more, and the
|
|
193
|
+
* thing you do without the figure is usually not the thing you do with it.
|
|
194
|
+
*/
|
|
195
|
+
async collect(options) {
|
|
196
|
+
const { expiresIn, timeout, onPoll, signal, reuse, ...input } = options;
|
|
197
|
+
if (input.externalId && reuse !== false) {
|
|
198
|
+
const existing = await this.collections.findByExternalId(input.externalId, signal);
|
|
199
|
+
if (existing) {
|
|
200
|
+
const settled = await existing.wait({
|
|
201
|
+
onPoll,
|
|
202
|
+
signal,
|
|
203
|
+
timeout: durationOrUndefined(timeout),
|
|
204
|
+
...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
|
|
205
|
+
});
|
|
206
|
+
return settled.toCollected();
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
const collection = await this.collections.create({
|
|
210
|
+
...input,
|
|
211
|
+
expiresAt: options.expiresAt ??
|
|
212
|
+
new Date(Date.now() + durationMs(expiresIn ?? DEFAULT_EXPIRY)).toISOString(),
|
|
213
|
+
}, signal);
|
|
214
|
+
const settled = await collection.wait({
|
|
215
|
+
onPoll,
|
|
216
|
+
signal,
|
|
217
|
+
timeout: durationOrUndefined(timeout) ?? (this.development ? 2_000 : undefined),
|
|
218
|
+
...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
|
|
219
|
+
});
|
|
220
|
+
return settled.toCollected();
|
|
221
|
+
}
|
|
115
222
|
/** Publish HTML to a secure URL. The other half of the product, one call in. */
|
|
116
223
|
publish(input, signal) {
|
|
117
224
|
return this.reports.publish(input, signal);
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { HttpClient } from "./http.js";
|
|
2
|
+
import type { CreateReviewInput, ListReviewsInput, ReviewData, ReviewOutcome } from "./types.js";
|
|
3
|
+
/**
|
|
4
|
+
* Ask people to read what you made and say whether it is right.
|
|
5
|
+
*
|
|
6
|
+
* The sibling of approvals, and the difference is worth keeping straight: an
|
|
7
|
+
* approval asks permission for something that has not happened, a review asks
|
|
8
|
+
* judgement on something that has. The waiting is the same shape, so the
|
|
9
|
+
* polling is shared.
|
|
10
|
+
*/
|
|
11
|
+
export interface ReviewWaitOptions {
|
|
12
|
+
/** Called after every poll, for a progress line in a CLI. */
|
|
13
|
+
onPoll?: (review: ReviewData) => void;
|
|
14
|
+
/**
|
|
15
|
+
* Give up after this many milliseconds and throw `DeliverdTimeoutError`.
|
|
16
|
+
* Omitted, the wait ends when the review does — which, for a review with no
|
|
17
|
+
* `expiresAt`, may be never. Set one or the other.
|
|
18
|
+
*/
|
|
19
|
+
timeout?: number;
|
|
20
|
+
signal?: AbortSignal;
|
|
21
|
+
/** How long between polls, as the wait lengthens. Rarely worth changing. */
|
|
22
|
+
pollIntervals?: readonly number[];
|
|
23
|
+
}
|
|
24
|
+
/** A review, and what you can do with it. */
|
|
25
|
+
export declare class Review {
|
|
26
|
+
private readonly http;
|
|
27
|
+
private data;
|
|
28
|
+
constructor(http: HttpClient, data: ReviewData);
|
|
29
|
+
get id(): string;
|
|
30
|
+
get status(): ReviewData["status"];
|
|
31
|
+
/** The page the reviewer reads and decides on. */
|
|
32
|
+
get url(): string;
|
|
33
|
+
get title(): string;
|
|
34
|
+
get verdicts(): ReviewData["verdicts"];
|
|
35
|
+
/** How many comment threads the reviewers opened while reading. */
|
|
36
|
+
get threadCount(): number;
|
|
37
|
+
/** The one to branch on. False for changes requested, expired and cancelled. */
|
|
38
|
+
get approved(): boolean;
|
|
39
|
+
get changesRequested(): boolean;
|
|
40
|
+
get expired(): boolean;
|
|
41
|
+
get cancelled(): boolean;
|
|
42
|
+
get pending(): boolean;
|
|
43
|
+
/** Everything the API returned, if you want a field the getters do not name. */
|
|
44
|
+
toJSON(): ReviewData;
|
|
45
|
+
toOutcome(): ReviewOutcome;
|
|
46
|
+
refresh(signal?: AbortSignal): Promise<this>;
|
|
47
|
+
/** Withdraw it. The row stays as evidence of what was asked and dropped. */
|
|
48
|
+
cancel(signal?: AbortSignal): Promise<this>;
|
|
49
|
+
/**
|
|
50
|
+
* Block until the reviewers settle it, then return.
|
|
51
|
+
*
|
|
52
|
+
* Resolves on every ending, including changes requested — that is an answer
|
|
53
|
+
* and the most useful one, because it comes with the threads that say what
|
|
54
|
+
* to change. It throws only when the wait itself failed: a timeout, an
|
|
55
|
+
* abort, or an API that could not be reached.
|
|
56
|
+
*/
|
|
57
|
+
wait(options?: ReviewWaitOptions): Promise<this>;
|
|
58
|
+
}
|
|
59
|
+
export declare class Reviews {
|
|
60
|
+
private readonly http;
|
|
61
|
+
constructor(http: HttpClient);
|
|
62
|
+
/**
|
|
63
|
+
* Ask. Returns as soon as the request is filed — the reviewers are being
|
|
64
|
+
* told while this resolves — so call `wait()` next, or keep the id and poll
|
|
65
|
+
* later.
|
|
66
|
+
*/
|
|
67
|
+
create(input: CreateReviewInput, signal?: AbortSignal): Promise<Review>;
|
|
68
|
+
get(id: string, signal?: AbortSignal): Promise<Review>;
|
|
69
|
+
list(input?: ListReviewsInput, signal?: AbortSignal): Promise<Review[]>;
|
|
70
|
+
/** Ask and wait, for the common case where there is nothing to do between. */
|
|
71
|
+
request(input: CreateReviewInput, options?: ReviewWaitOptions): Promise<Review>;
|
|
72
|
+
/**
|
|
73
|
+
* The same request as before, when there was one — so restarting a crashed
|
|
74
|
+
* agent does not ask the same people twice. The caveat is the one
|
|
75
|
+
* `approvals.findByExternalId` carries: two concurrent calls can still both
|
|
76
|
+
* find nothing and both create.
|
|
77
|
+
*/
|
|
78
|
+
findByExternalId(externalId: string, signal?: AbortSignal): Promise<Review | null>;
|
|
79
|
+
}
|
|
80
|
+
//# sourceMappingURL=reviews.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"reviews.d.ts","sourceRoot":"","sources":["../src/reviews.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AAEH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAQD,6CAA6C;AAC7C,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,IAAI;gBADK,IAAI,EAAE,UAAU,EACzB,IAAI,EAAE,UAAU;IAG1B,IAAI,EAAE,IAAI,MAAM,CAAyB;IACzC,IAAI,MAAM,IAAI,UAAU,CAAC,QAAQ,CAAC,CAA6B;IAC/D,kDAAkD;IAClD,IAAI,GAAG,IAAI,MAAM,CAA0B;IAC3C,IAAI,KAAK,IAAI,MAAM,CAA4B;IAC/C,IAAI,QAAQ,IAAI,UAAU,CAAC,UAAU,CAAC,CAA+B;IACrE,mEAAmE;IACnE,IAAI,WAAW,IAAI,MAAM,CAAkC;IAE3D,gFAAgF;IAChF,IAAI,QAAQ,IAAI,OAAO,CAA4C;IACnE,IAAI,gBAAgB,IAAI,OAAO,CAAqD;IACpF,IAAI,OAAO,IAAI,OAAO,CAA2C;IACjE,IAAI,SAAS,IAAI,OAAO,CAA6C;IACrE,IAAI,OAAO,IAAI,OAAO,CAA2C;IAEjE,gFAAgF;IAChF,MAAM,IAAI,UAAU;IAEpB,SAAS,IAAI,aAAa;IAapB,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IASlD,4EAA4E;IACtE,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IASjD;;;;;;;OAOG;IACG,IAAI,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;CAyB3D;AAmBD,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAUvE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAStD,IAAI,CAAC,KAAK,GAAE,gBAAqB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAejF,8EAA8E;IACxE,OAAO,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC;IAKzF;;;;;OAKG;IACG,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAIzF"}
|
package/dist/reviews.js
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
import { DeliverdError, DeliverdTimeoutError } from "./errors.js";
|
|
2
|
+
import { POLL_SCHEDULE } from "./approvals.js";
|
|
3
|
+
function pollDelay(poll, schedule) {
|
|
4
|
+
const base = schedule[Math.min(poll, schedule.length - 1)] ?? 60_000;
|
|
5
|
+
// Jitter, so a hundred agents started by the same cron do not arrive together.
|
|
6
|
+
return base * 0.75 + Math.random() * base * 0.5;
|
|
7
|
+
}
|
|
8
|
+
/** A review, and what you can do with it. */
|
|
9
|
+
export class Review {
|
|
10
|
+
http;
|
|
11
|
+
data;
|
|
12
|
+
constructor(http, data) {
|
|
13
|
+
this.http = http;
|
|
14
|
+
this.data = data;
|
|
15
|
+
}
|
|
16
|
+
get id() { return this.data.id; }
|
|
17
|
+
get status() { return this.data.status; }
|
|
18
|
+
/** The page the reviewer reads and decides on. */
|
|
19
|
+
get url() { return this.data.url; }
|
|
20
|
+
get title() { return this.data.title; }
|
|
21
|
+
get verdicts() { return this.data.verdicts; }
|
|
22
|
+
/** How many comment threads the reviewers opened while reading. */
|
|
23
|
+
get threadCount() { return this.data.threadCount; }
|
|
24
|
+
/** The one to branch on. False for changes requested, expired and cancelled. */
|
|
25
|
+
get approved() { return this.data.status === "approved"; }
|
|
26
|
+
get changesRequested() { return this.data.status === "changes_requested"; }
|
|
27
|
+
get expired() { return this.data.status === "expired"; }
|
|
28
|
+
get cancelled() { return this.data.status === "cancelled"; }
|
|
29
|
+
get pending() { return this.data.status === "pending"; }
|
|
30
|
+
/** Everything the API returned, if you want a field the getters do not name. */
|
|
31
|
+
toJSON() { return this.data; }
|
|
32
|
+
toOutcome() {
|
|
33
|
+
const status = this.data.status === "pending" ? "expired" : this.data.status;
|
|
34
|
+
return {
|
|
35
|
+
approved: this.data.status === "approved",
|
|
36
|
+
status,
|
|
37
|
+
verdicts: this.data.verdicts,
|
|
38
|
+
threadCount: this.data.threadCount,
|
|
39
|
+
id: this.data.id,
|
|
40
|
+
url: this.data.url,
|
|
41
|
+
review: this.data,
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
async refresh(signal) {
|
|
45
|
+
this.data = await this.http.request({
|
|
46
|
+
method: "GET",
|
|
47
|
+
path: `/reviews/${this.data.id}`,
|
|
48
|
+
signal,
|
|
49
|
+
});
|
|
50
|
+
return this;
|
|
51
|
+
}
|
|
52
|
+
/** Withdraw it. The row stays as evidence of what was asked and dropped. */
|
|
53
|
+
async cancel(signal) {
|
|
54
|
+
this.data = await this.http.request({
|
|
55
|
+
method: "POST",
|
|
56
|
+
path: `/reviews/${this.data.id}/cancel`,
|
|
57
|
+
signal,
|
|
58
|
+
});
|
|
59
|
+
return this;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Block until the reviewers settle it, then return.
|
|
63
|
+
*
|
|
64
|
+
* Resolves on every ending, including changes requested — that is an answer
|
|
65
|
+
* and the most useful one, because it comes with the threads that say what
|
|
66
|
+
* to change. It throws only when the wait itself failed: a timeout, an
|
|
67
|
+
* abort, or an API that could not be reached.
|
|
68
|
+
*/
|
|
69
|
+
async wait(options = {}) {
|
|
70
|
+
const deadline = options.timeout !== undefined ? Date.now() + options.timeout : undefined;
|
|
71
|
+
let poll = 0;
|
|
72
|
+
if (!this.pending)
|
|
73
|
+
return this;
|
|
74
|
+
for (;;) {
|
|
75
|
+
if (options.signal?.aborted) {
|
|
76
|
+
throw new DeliverdError(0, "aborted", "The wait was aborted.", undefined, {
|
|
77
|
+
cause: options.signal.reason,
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
if (deadline !== undefined && Date.now() >= deadline) {
|
|
81
|
+
throw new DeliverdTimeoutError(`Nobody finished reviewing "${this.data.title}" within the timeout. It is still open at ${this.data.url}.`);
|
|
82
|
+
}
|
|
83
|
+
const delay = pollDelay(poll++, options.pollIntervals ?? POLL_SCHEDULE);
|
|
84
|
+
const remaining = deadline === undefined ? delay : Math.min(delay, deadline - Date.now());
|
|
85
|
+
await sleep(Math.max(0, remaining), options.signal);
|
|
86
|
+
await this.refresh(options.signal);
|
|
87
|
+
options.onPoll?.(this.data);
|
|
88
|
+
if (!this.pending)
|
|
89
|
+
return this;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
function sleep(ms, signal) {
|
|
94
|
+
return new Promise((resolve, reject) => {
|
|
95
|
+
if (signal?.aborted) {
|
|
96
|
+
return reject(new DeliverdError(0, "aborted", "The wait was aborted."));
|
|
97
|
+
}
|
|
98
|
+
const timer = setTimeout(() => {
|
|
99
|
+
signal?.removeEventListener("abort", onAbort);
|
|
100
|
+
resolve();
|
|
101
|
+
}, ms);
|
|
102
|
+
const onAbort = () => {
|
|
103
|
+
clearTimeout(timer);
|
|
104
|
+
reject(new DeliverdError(0, "aborted", "The wait was aborted."));
|
|
105
|
+
};
|
|
106
|
+
signal?.addEventListener("abort", onAbort, { once: true });
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
export class Reviews {
|
|
110
|
+
http;
|
|
111
|
+
constructor(http) {
|
|
112
|
+
this.http = http;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Ask. Returns as soon as the request is filed — the reviewers are being
|
|
116
|
+
* told while this resolves — so call `wait()` next, or keep the id and poll
|
|
117
|
+
* later.
|
|
118
|
+
*/
|
|
119
|
+
async create(input, signal) {
|
|
120
|
+
const data = await this.http.request({
|
|
121
|
+
method: "POST",
|
|
122
|
+
path: "/reviews",
|
|
123
|
+
body: input,
|
|
124
|
+
signal,
|
|
125
|
+
});
|
|
126
|
+
return new Review(this.http, data);
|
|
127
|
+
}
|
|
128
|
+
async get(id, signal) {
|
|
129
|
+
const data = await this.http.request({
|
|
130
|
+
method: "GET",
|
|
131
|
+
path: `/reviews/${id}`,
|
|
132
|
+
signal,
|
|
133
|
+
});
|
|
134
|
+
return new Review(this.http, data);
|
|
135
|
+
}
|
|
136
|
+
async list(input = {}, signal) {
|
|
137
|
+
const { reviews } = await this.http.request({
|
|
138
|
+
method: "GET",
|
|
139
|
+
path: "/reviews",
|
|
140
|
+
query: {
|
|
141
|
+
status: input.status,
|
|
142
|
+
externalId: input.externalId,
|
|
143
|
+
reportId: input.reportId,
|
|
144
|
+
limit: input.limit,
|
|
145
|
+
},
|
|
146
|
+
signal,
|
|
147
|
+
});
|
|
148
|
+
return reviews.map((r) => new Review(this.http, r));
|
|
149
|
+
}
|
|
150
|
+
/** Ask and wait, for the common case where there is nothing to do between. */
|
|
151
|
+
async request(input, options = {}) {
|
|
152
|
+
const review = await this.create(input, options.signal);
|
|
153
|
+
return review.wait(options);
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* The same request as before, when there was one — so restarting a crashed
|
|
157
|
+
* agent does not ask the same people twice. The caveat is the one
|
|
158
|
+
* `approvals.findByExternalId` carries: two concurrent calls can still both
|
|
159
|
+
* find nothing and both create.
|
|
160
|
+
*/
|
|
161
|
+
async findByExternalId(externalId, signal) {
|
|
162
|
+
const found = await this.list({ externalId, limit: 1 }, signal);
|
|
163
|
+
return found[0] ?? null;
|
|
164
|
+
}
|
|
165
|
+
}
|