@deliverd/sdk 0.1.0 → 0.2.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 CHANGED
@@ -61,6 +61,10 @@ Or flip a whole test suite from the command line with
61
61
  nothing else, so the code it exercises is the code that will run in
62
62
  production — the same retries, the same errors, the same waiting.
63
63
 
64
+ It simulates `review()` too, and there a rejection becomes "changes requested"
65
+ with a note attached, because that is what saying no to a piece of work means
66
+ and a refusal with no reason is useless.
67
+
64
68
  ## Configuration
65
69
 
66
70
  There is none. `new Deliverd()` reads `DELIVERD_API_KEY`, and
@@ -150,18 +154,64 @@ neither can be waited on for ever, which is what `await` means.
150
154
  ## The primitives
151
155
 
152
156
  ```ts
153
- await deliverd.approve({ title }); // ask, and wait for the answer
157
+ await deliverd.approve({ title }); // ask permission, and wait for the answer
158
+ await deliverd.review({ title, reportId, reviewers }); // ask whether it is right
154
159
  await deliverd.confirm({ title }); // a yes or no on something small → boolean
155
160
  await deliverd.publish({ title, content }); // get the work to the people who need it
156
161
  ```
157
162
 
158
- `review()` and `collect()` — a human reading an artifact and giving a verdict,
159
- and a human filling in what your agent is missing — are the next two, and they
160
- are **not in this package yet**, because the API behind them is not built yet.
161
- They are stages three and four of
163
+ `collect()` — a human filling in what your agent is missing — is the last one,
164
+ and it is **not in this package yet**, because the API behind it is not built.
165
+ It is a stage of
162
166
  [the plan](https://github.com/davidpreid/deliverd/blob/main/docs/control-layer.md).
163
- Shipping them now as methods that throw would put a lie in your autocomplete,
164
- which is worse than their absence.
167
+ Shipping it now as a method that throws would put a lie in your autocomplete,
168
+ which is worse than its absence.
169
+
170
+ ## Reviewing
171
+
172
+ `approve()` asks permission before you act. `review()` asks whether what you
173
+ already produced is right.
174
+
175
+ ```ts
176
+ const outcome = await deliverd.review({
177
+ title: "Q3 board pack",
178
+ reportId: report.id,
179
+ instructions: "Check the figures against the ledger.",
180
+ reviewers: ["partner@firm.example"],
181
+ });
182
+
183
+ if (!outcome.approved) await revise(outcome.verdicts);
184
+ ```
185
+
186
+ It resolves on `changes_requested` as well as `approved`, because that is an
187
+ answer — usually the more useful one. `outcome.verdicts` is what each reviewer
188
+ said, and `outcome.threadCount` is how many comments they left anchored to the
189
+ passages they meant. Read those with `deliverd.comments.list(reportId)` and
190
+ turn them into the next version with `deliverd.reports.revisionBrief(reportId)`.
191
+
192
+ A reviewer must be **an active member of your organisation, or a guest who can
193
+ already open the report** — anyone else is refused rather than emailed, which
194
+ is also what stops an agent reaching an address of its choosing. Share the
195
+ report with someone before naming them.
196
+
197
+ You cannot review your own request. One reviewer gives one verdict, and a
198
+ second is refused, because the first one is evidence. `requiredApprovals`
199
+ decides how many approvals settle it; a single `changes_requested` settles it
200
+ regardless, since collecting the rest after somebody has found a problem spends
201
+ their afternoon on a question already answered.
202
+
203
+ ```ts
204
+ await deliverd.reviews.create(input); // ask without waiting
205
+ await deliverd.reviews.get(id);
206
+ await deliverd.reviews.list({ status: "pending" });
207
+ await deliverd.reviews.findByExternalId("pack_2026q3");
208
+ await review.wait({ onPoll });
209
+ await review.cancel();
210
+ ```
211
+
212
+ There is no method that returns a verdict, and there is no endpoint behind one.
213
+ A verdict is a person's judgement; your key is not a person. They record theirs
214
+ on the page, where they have just read the work.
165
215
 
166
216
  Under `approve()` is the full surface, when you want it:
167
217
 
package/dist/dev.d.ts CHANGED
@@ -36,7 +36,7 @@ export interface DevelopmentOptions {
36
36
  log?: boolean;
37
37
  }
38
38
  /**
39
- * A `fetch` that serves the approvals API from memory.
39
+ * A `fetch` that serves the approvals and reviews APIs from memory.
40
40
  *
41
41
  * Deliberately narrow: it answers the calls the primitives make and 501s the
42
42
  * rest, with a message saying so, rather than pretending to be the whole API
package/dist/dev.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AAElF,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,GAAG,CAAC,CAAC,OAAO,EAAE,YAAY,KAAK,kBAAkB,CAAC,CAAC;IAC/E,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAcD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,UAAU,CAAC,KAAK,CAmG1F"}
1
+ {"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AAElF,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,GAAG,CAAC,CAAC,OAAO,EAAE,YAAY,KAAK,kBAAkB,CAAC,CAAC;IAC/E,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAcD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,UAAU,CAAC,KAAK,CAyK1F"}
package/dist/dev.js CHANGED
@@ -1,7 +1,7 @@
1
1
  const DEFAULT_QUESTION = "Has this been through staging?";
2
2
  let counter = 0;
3
3
  /**
4
- * A `fetch` that serves the approvals API from memory.
4
+ * A `fetch` that serves the approvals and reviews APIs from memory.
5
5
  *
6
6
  * Deliberately narrow: it answers the calls the primitives make and 501s the
7
7
  * rest, with a message saying so, rather than pretending to be the whole API
@@ -9,6 +9,7 @@ let counter = 0;
9
9
  */
10
10
  export function developmentFetch(options = {}) {
11
11
  const store = new Map();
12
+ const reviewStore = new Map();
12
13
  return (async (input, init) => {
13
14
  const url = new URL(String(input));
14
15
  const path = url.pathname.replace(/^\/api\/v1/, "");
@@ -90,10 +91,74 @@ export function developmentFetch(options = {}) {
90
91
  settle(stored);
91
92
  return json(stored.data);
92
93
  }
94
+ if (method === "POST" && path === "/reviews") {
95
+ const id = `rev_dev_${++counter}`;
96
+ /*
97
+ * The same outcome switch as approvals, mapped onto a review's endings:
98
+ * a rejection is "changes requested", because that is what saying no to
99
+ * a piece of work means. A simulated question has nothing to ask about
100
+ * here — there is no question mechanism on a review — so it approves.
101
+ */
102
+ const outcome = resolveOutcome(options.outcome, body);
103
+ const verdict = outcome === "rejected" ? "changes_requested" : "approved";
104
+ const reviewers = (body.reviewers ?? []).map((email, i) => ({
105
+ kind: "user",
106
+ id: `usr_dev_${i + 1}`,
107
+ label: email,
108
+ }));
109
+ const data = {
110
+ id,
111
+ status: "pending",
112
+ url: `https://deliverd.dev/reviews/${id}`,
113
+ title: String(body.title ?? "Untitled"),
114
+ instructions: body.instructions ?? null,
115
+ reportId: body.reportId ?? null,
116
+ versionId: body.versionId ?? null,
117
+ externalId: body.externalId ?? null,
118
+ metadata: body.metadata ?? {},
119
+ requestedBy: "You (development mode)",
120
+ requiredApprovals: body.requiredApprovals ?? 1,
121
+ reviewers,
122
+ verdicts: [],
123
+ threadCount: 0,
124
+ settledAt: null,
125
+ expiresAt: body.expiresAt ?? null,
126
+ createdAt: new Date().toISOString(),
127
+ };
128
+ reviewStore.set(id, {
129
+ data,
130
+ settleAt: Date.now() + (options.delay ?? 0),
131
+ verdict,
132
+ timeout: outcome === "timeout",
133
+ });
134
+ if (options.log !== false)
135
+ announceReview(data, verdict, outcome === "timeout");
136
+ return json(data, 201);
137
+ }
138
+ const reviewMatch = /^\/reviews\/([^/]+)(\/cancel)?$/.exec(path);
139
+ if (reviewMatch) {
140
+ const stored = reviewStore.get(reviewMatch[1]);
141
+ if (!stored) {
142
+ return json({ error: { code: "not_found", message: "No such review in this development session." } }, 404);
143
+ }
144
+ if (reviewMatch[2] === "/cancel") {
145
+ stored.data.status = "cancelled";
146
+ return json(stored.data);
147
+ }
148
+ settleReview(stored);
149
+ return json(stored.data);
150
+ }
151
+ if (method === "GET" && path === "/reviews") {
152
+ const externalId = url.searchParams.get("externalId");
153
+ const all = [...reviewStore.values()].map((r) => r.data);
154
+ return json({
155
+ reviews: externalId ? all.filter((r) => r.externalId === externalId) : all,
156
+ });
157
+ }
93
158
  return json({
94
159
  error: {
95
160
  code: "not_in_development_mode",
96
- message: `Development mode simulates approvals only, and something called ${method} ${path}. Use a real API key for the rest of the API.`,
161
+ message: `Development mode simulates approvals and reviews only, and something called ${method} ${path}. Use a real API key for the rest of the API.`,
97
162
  },
98
163
  }, 501);
99
164
  });
@@ -145,3 +210,35 @@ function announce(data, outcome) {
145
210
  lines.push(" │", ` │ Simulating: ${outcome}${outcome === "question" ? " (needs an onQuestion handler)" : ""}`, " └───────────────────────────────────────────────────────", "");
146
211
  console.log(lines.join("\n"));
147
212
  }
213
+ /** Settle it once its moment has passed, unless it is meant to hang. */
214
+ function settleReview(stored) {
215
+ if (stored.timeout || stored.data.status !== "pending")
216
+ return;
217
+ if (Date.now() < stored.settleAt)
218
+ return;
219
+ stored.data.verdicts = [
220
+ {
221
+ verdict: stored.verdict,
222
+ by: stored.data.reviewers[0]?.label ?? "A reviewer (development mode)",
223
+ note: stored.verdict === "changes_requested"
224
+ ? "Simulated: the figures on page two do not tie back."
225
+ : null,
226
+ at: new Date().toISOString(),
227
+ },
228
+ ];
229
+ stored.data.status = stored.verdict;
230
+ stored.data.settledAt = new Date().toISOString();
231
+ }
232
+ function announceReview(data, verdict, willHang) {
233
+ const lines = [
234
+ ` ┌─ Deliverd · development mode ─────────────────────────`,
235
+ ` │ ${data.title}`,
236
+ ...(data.instructions ? [` │ Check: ${data.instructions}`] : []),
237
+ ` │ Reviewers: ${data.reviewers.map((r) => r.label).join(", ") || "nobody named"}`,
238
+ ` │`,
239
+ ` │ Simulating: ${willHang ? "nobody reviews it" : verdict.replace("_", " ")}`,
240
+ ` └───────────────────────────────────────────────────────`,
241
+ "",
242
+ ];
243
+ console.log(lines.join("\n"));
244
+ }
package/dist/index.d.ts CHANGED
@@ -1,12 +1,14 @@
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";
4
5
  import { Webhooks } from "./webhooks.js";
5
6
  import { type DevelopmentOptions } from "./dev.js";
6
7
  import { type Duration } from "./duration.js";
7
- import type { CreateApprovalInput, Decision, PublishReportInput, PublishResult } from "./types.js";
8
+ import type { CreateApprovalInput, CreateReviewInput, Decision, PublishReportInput, PublishResult, ReviewOutcome } from "./types.js";
8
9
  export { Approval, Approvals, POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
9
10
  export { Comments, Reports } from "./reports.js";
11
+ export { Review, Reviews, type ReviewWaitOptions } from "./reviews.js";
10
12
  export { constructEvent, DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER, TOLERANCE_SECONDS, verifySignature, Webhooks, } from "./webhooks.js";
11
13
  export { DeliverdError, DeliverdTimeoutError } from "./errors.js";
12
14
  export { DEFAULT_BASE_URL, type ClientOptions } from "./http.js";
@@ -47,6 +49,23 @@ export interface ApproveOptions extends Omit<CreateApprovalInput, "expiresAt"> {
47
49
  */
48
50
  reuse?: boolean;
49
51
  }
52
+ /** Everything `review()` takes, plus the conveniences it adds on top. */
53
+ export interface ReviewOptions extends Omit<CreateReviewInput, "expiresAt"> {
54
+ /** `"4h"`, `"30m"`, `"2d"`, or milliseconds. Default 24 hours. */
55
+ expiresIn?: Duration;
56
+ /** An exact moment instead, if you have one. */
57
+ expiresAt?: string;
58
+ /** Called after each poll — a progress line in a CLI. */
59
+ onPoll?: ReviewWaitOptions["onPoll"];
60
+ /** Give up waiting after this. The review stays open until it expires. */
61
+ timeout?: Duration;
62
+ signal?: AbortSignal;
63
+ /**
64
+ * With an `externalId`, reuse an existing review rather than filing a
65
+ * second one, so a restarted agent does not ask the same people twice.
66
+ */
67
+ reuse?: boolean;
68
+ }
50
69
  /**
51
70
  * Deliverd: you build the action, Deliverd handles the human.
52
71
  *
@@ -68,6 +87,7 @@ export interface ApproveOptions extends Omit<CreateApprovalInput, "expiresAt"> {
68
87
  */
69
88
  export declare class Deliverd {
70
89
  readonly approvals: Approvals;
90
+ readonly reviews: Reviews;
71
91
  readonly reports: Reports;
72
92
  readonly comments: Comments;
73
93
  readonly webhooks: Webhooks;
@@ -95,6 +115,28 @@ export declare class Deliverd {
95
115
  * `approve()`.
96
116
  */
97
117
  confirm(options: ApproveOptions): Promise<boolean>;
118
+ /**
119
+ * Ask people to read what you made, and wait for their answer.
120
+ *
121
+ * The other half of judgement. `approve()` asks permission before you act;
122
+ * this asks whether what you already produced is right, and comes back with
123
+ * the reviewers' verdicts and a count of the comment threads they opened.
124
+ *
125
+ * ```ts
126
+ * const outcome = await deliverd.review({
127
+ * title: "Q3 board pack",
128
+ * reportId: report.id,
129
+ * instructions: "Check the figures against the ledger.",
130
+ * reviewers: ["partner@firm.example"],
131
+ * });
132
+ * if (!outcome.approved) await revise(outcome.verdicts);
133
+ * ```
134
+ *
135
+ * Resolves on changes requested as well as approval, because that is an
136
+ * answer — usually the more useful one. Reviews expire after a day unless
137
+ * you say otherwise, so a wait always ends.
138
+ */
139
+ review(options: ReviewOptions): Promise<ReviewOutcome>;
98
140
  /** Publish HTML to a secure URL. The other half of the product, one call in. */
99
141
  publish(input: PublishReportInput, signal?: AbortSignal): Promise<PublishResult>;
100
142
  }
@@ -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;IAkBzC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IA0CzD;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAKxD,gFAAgF;IAChF,OAAO,CAAC,KAAK,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;CAGjF;AAoBD,eAAO,MAAM,QAAQ,EAAE,QAMrB,CAAC;AAEH,eAAe,QAAQ,CAAC"}
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,13 @@
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";
4
5
  import { Webhooks } from "./webhooks.js";
5
6
  import { developmentFetch } from "./dev.js";
6
7
  import { durationMs } from "./duration.js";
7
8
  export { Approval, Approvals, POLL_SCHEDULE } from "./approvals.js";
8
9
  export { Comments, Reports } from "./reports.js";
10
+ export { Review, Reviews } from "./reviews.js";
9
11
  export { constructEvent, DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER, TOLERANCE_SECONDS, verifySignature, Webhooks, } from "./webhooks.js";
10
12
  export { DeliverdError, DeliverdTimeoutError } from "./errors.js";
11
13
  export { DEFAULT_BASE_URL } from "./http.js";
@@ -33,6 +35,7 @@ export const DEFAULT_EXPIRY = "24h";
33
35
  */
34
36
  export class Deliverd {
35
37
  approvals;
38
+ reviews;
36
39
  reports;
37
40
  comments;
38
41
  webhooks;
@@ -50,6 +53,7 @@ export class Deliverd {
50
53
  fetch: this.development ? developmentFetch(options.development) : options.fetch,
51
54
  });
52
55
  this.approvals = new Approvals(this.http);
56
+ this.reviews = new Reviews(this.http);
53
57
  this.reports = new Reports(this.http);
54
58
  this.comments = new Comments(this.http);
55
59
  this.webhooks = new Webhooks();
@@ -112,6 +116,56 @@ export class Deliverd {
112
116
  const decision = await this.approve({ risk: "low", expiresIn: "1h", ...options });
113
117
  return decision.approved;
114
118
  }
119
+ /**
120
+ * Ask people to read what you made, and wait for their answer.
121
+ *
122
+ * The other half of judgement. `approve()` asks permission before you act;
123
+ * this asks whether what you already produced is right, and comes back with
124
+ * the reviewers' verdicts and a count of the comment threads they opened.
125
+ *
126
+ * ```ts
127
+ * const outcome = await deliverd.review({
128
+ * title: "Q3 board pack",
129
+ * reportId: report.id,
130
+ * instructions: "Check the figures against the ledger.",
131
+ * reviewers: ["partner@firm.example"],
132
+ * });
133
+ * if (!outcome.approved) await revise(outcome.verdicts);
134
+ * ```
135
+ *
136
+ * Resolves on changes requested as well as approval, because that is an
137
+ * answer — usually the more useful one. Reviews expire after a day unless
138
+ * you say otherwise, so a wait always ends.
139
+ */
140
+ async review(options) {
141
+ const { expiresIn, timeout, onPoll, signal, reuse, ...input } = options;
142
+ if (input.externalId && reuse !== false) {
143
+ const existing = await this.reviews.findByExternalId(input.externalId, signal);
144
+ if (existing) {
145
+ const settled = await existing.wait({
146
+ onPoll,
147
+ signal,
148
+ timeout: durationOrUndefined(timeout),
149
+ ...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
150
+ });
151
+ return settled.toOutcome();
152
+ }
153
+ }
154
+ const review = await this.reviews.create({
155
+ ...input,
156
+ expiresAt: options.expiresAt ??
157
+ new Date(Date.now() + durationMs(expiresIn ?? DEFAULT_EXPIRY)).toISOString(),
158
+ }, signal);
159
+ const settled = await review.wait({
160
+ onPoll,
161
+ signal,
162
+ // Same reasoning as approve(): in development the reviewer is imaginary
163
+ // and instant, so a wait still running after a moment will never settle.
164
+ timeout: durationOrUndefined(timeout) ?? (this.development ? 2_000 : undefined),
165
+ ...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
166
+ });
167
+ return settled.toOutcome();
168
+ }
115
169
  /** Publish HTML to a secure URL. The other half of the product, one call in. */
116
170
  publish(input, signal) {
117
171
  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"}
@@ -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
+ }