@deliverd/sdk 0.11.0 → 0.11.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/LICENSE +21 -21
- package/README.md +654 -654
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +533 -0
- package/package.json +59 -59
- package/src/adapters/ai-sdk.ts +59 -59
- package/src/adapters/claude-agent-sdk.ts +90 -90
- package/src/adapters/index.ts +23 -23
- package/src/adapters/langgraph.ts +202 -202
- package/src/adapters/openai-agents.ts +112 -112
- package/src/adapters/shared.ts +179 -179
- package/src/approvals.ts +342 -342
- package/src/collections.ts +247 -247
- package/src/dev.ts +868 -868
- package/src/duration.ts +21 -21
- package/src/errors.ts +62 -62
- package/src/flows.ts +222 -222
- package/src/gates.ts +366 -366
- package/src/http.ts +217 -217
- package/src/index.ts +444 -444
- package/src/messages.ts +209 -209
- package/src/paging.ts +64 -64
- package/src/released.ts +4049 -3516
- package/src/reports.ts +490 -490
- package/src/reviews.ts +236 -236
- package/src/types.ts +1107 -1107
- package/src/webhooks.ts +117 -117
package/README.md
CHANGED
|
@@ -1,654 +1,654 @@
|
|
|
1
|
-
# @deliverd/sdk
|
|
2
|
-
|
|
3
|
-
You build the action. Deliverd handles the human.
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
npm install @deliverd/sdk
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
```ts
|
|
10
|
-
import { deliverd } from "@deliverd/sdk";
|
|
11
|
-
|
|
12
|
-
const decision = await deliverd.approve({ title: "Deploy to production" });
|
|
13
|
-
|
|
14
|
-
if (decision.approved) await deploy();
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
That is the integration. What it stands in for: an approval page, the emails
|
|
18
|
-
and the reminders, identity and single sign-on, who is allowed to decide, a
|
|
19
|
-
table to keep it in, an audit trail, and the dashboard somebody uses to do it.
|
|
20
|
-
None of that is yours to build.
|
|
21
|
-
|
|
22
|
-
Your approver gets an email and a notification, opens a page that works on a
|
|
23
|
-
phone, and approves, rejects with a reason, or asks your agent a question.
|
|
24
|
-
Every step is on the record.
|
|
25
|
-
|
|
26
|
-
## Before you have an account
|
|
27
|
-
|
|
28
|
-
```ts
|
|
29
|
-
import { Deliverd } from "@deliverd/sdk";
|
|
30
|
-
|
|
31
|
-
const deliverd = new Deliverd({ mode: "development" });
|
|
32
|
-
const decision = await deliverd.approve({ title: "Deploy to production" });
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
No key, no network, nobody interrupted. It prints what the approver would have
|
|
36
|
-
seen and answers instantly:
|
|
37
|
-
|
|
38
|
-
```
|
|
39
|
-
┌─ Deliverd · development mode ─────────────────────────
|
|
40
|
-
│ Refund £1,240 to Acme
|
|
41
|
-
│ Duplicate charge on invoice 4821.
|
|
42
|
-
│ Risk: high
|
|
43
|
-
│ ✓ Within the refund limit
|
|
44
|
-
│ To: finance@example.com
|
|
45
|
-
│
|
|
46
|
-
│ Simulating: approved
|
|
47
|
-
└───────────────────────────────────────────────────────
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
All four things that can happen are one word away, including the one people
|
|
51
|
-
forget to write:
|
|
52
|
-
|
|
53
|
-
```ts
|
|
54
|
-
new Deliverd({ mode: "development", development: { outcome: "rejected" } });
|
|
55
|
-
new Deliverd({ mode: "development", development: { outcome: "timeout" } });
|
|
56
|
-
new Deliverd({ mode: "development", development: { outcome: "question" } });
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
Or flip a whole test suite from the command line with
|
|
60
|
-
`DELIVERD_DEV_OUTCOME=rejected`. Development mode swaps out the network and
|
|
61
|
-
nothing else, so the code it exercises is the code that will run in
|
|
62
|
-
production — the same retries, the same errors, the same waiting.
|
|
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
|
-
|
|
68
|
-
## Configuration
|
|
69
|
-
|
|
70
|
-
There is none. `new Deliverd()` reads `DELIVERD_API_KEY`, and
|
|
71
|
-
`import { deliverd }` does not even need that line. Everything below has a
|
|
72
|
-
default that works:
|
|
73
|
-
|
|
74
|
-
| | Default |
|
|
75
|
-
|---|---|
|
|
76
|
-
| Who decides | Your organisation's owners and admins, unless you name `approvers` |
|
|
77
|
-
| Expiry | 24 hours, so a wait always ends |
|
|
78
|
-
| Notifications | Email and in-app, to whoever has to decide |
|
|
79
|
-
| Retries | Transient failures and rate limits, honouring `Retry-After` |
|
|
80
|
-
| Audit | On. Every request, question and decision, with the actor |
|
|
81
|
-
| Correlation id | Generated per request and sent with it |
|
|
82
|
-
| Webhook signing | Already signed; verify with `constructEvent` |
|
|
83
|
-
| Lists | `list()` returns every row; it follows the cursor so you do not have to |
|
|
84
|
-
|
|
85
|
-
## Progressive depth
|
|
86
|
-
|
|
87
|
-
Level one is the five lines above. Level two adds context, which is what the
|
|
88
|
-
approver reads before deciding:
|
|
89
|
-
|
|
90
|
-
```ts
|
|
91
|
-
await deliverd.approve({
|
|
92
|
-
title: "Deploy release 4.2 to production",
|
|
93
|
-
description: "142 commits since 4.1. All checks green.",
|
|
94
|
-
risk: "high",
|
|
95
|
-
factors: [
|
|
96
|
-
{ label: "All checks green", status: "ok" },
|
|
97
|
-
{ label: "Touches the payments path", status: "warning", detail: "3 files under /billing" },
|
|
98
|
-
],
|
|
99
|
-
links: [{ label: "The diff", url: "https://github.com/…/compare/4.1...4.2" }],
|
|
100
|
-
approvers: ["dave@example.com"],
|
|
101
|
-
expiresIn: "4h",
|
|
102
|
-
externalId: "deploy_4842",
|
|
103
|
-
});
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
`externalId` is your own reference. Pass one and a restarted agent reuses the
|
|
107
|
-
request it already made rather than asking a second time.
|
|
108
|
-
|
|
109
|
-
## Answering the approver
|
|
110
|
-
|
|
111
|
-
The thing that makes this more than a pause button: a person can ask your
|
|
112
|
-
agent a question from the approval page, and your agent can answer it without
|
|
113
|
-
anyone leaving what they are doing.
|
|
114
|
-
|
|
115
|
-
```ts
|
|
116
|
-
await approval.wait({
|
|
117
|
-
onQuestion: async (question) => {
|
|
118
|
-
// Return a string and it is posted as the answer; return null to leave
|
|
119
|
-
// it for a person.
|
|
120
|
-
return await agent.ask(question.question);
|
|
121
|
-
},
|
|
122
|
-
});
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
Without a handler the question simply sits there — which is correct, because
|
|
126
|
-
the approver is waiting on an answer and nothing should move until they get
|
|
127
|
-
one or decide anyway.
|
|
128
|
-
|
|
129
|
-
## Waiting
|
|
130
|
-
|
|
131
|
-
`wait()` polls, backing off from two seconds to a minute with jitter, so a
|
|
132
|
-
hundred agents started by the same cron do not arrive together. It resolves
|
|
133
|
-
when the request settles, **including on a rejection** — a refusal is an
|
|
134
|
-
answer, and `if (approval.approved)` is the line that should follow.
|
|
135
|
-
|
|
136
|
-
It throws only when the wait itself failed:
|
|
137
|
-
|
|
138
|
-
```ts
|
|
139
|
-
try {
|
|
140
|
-
await approval.wait({ timeout: 30 * 60_000 });
|
|
141
|
-
} catch (err) {
|
|
142
|
-
if (err instanceof DeliverdTimeoutError) {
|
|
143
|
-
// Nobody decided in time. The request is still open at approval.url.
|
|
144
|
-
}
|
|
145
|
-
}
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
Give every request an `expiresAt` or every wait a `timeout`. A request with
|
|
149
|
-
neither can be waited on for ever, which is what `await` means.
|
|
150
|
-
|
|
151
|
-
`wait()` also takes an `AbortSignal`, and `onPoll` for a progress line.
|
|
152
|
-
|
|
153
|
-
## The primitives
|
|
154
|
-
|
|
155
|
-
```ts
|
|
156
|
-
await deliverd.gate({ action, input, externalId }); // may I? — your organisation answers
|
|
157
|
-
await deliverd.approve({ title }); // ask permission, and wait for the answer
|
|
158
|
-
await deliverd.review({ title, reportId, reviewers }); // ask whether it is right
|
|
159
|
-
await deliverd.collect({ title, questions, respondents }); // ask for what you lack
|
|
160
|
-
await deliverd.confirm({ title }); // a yes or no on something small → boolean
|
|
161
|
-
await deliverd.publish({ title, content }); // get the work to the people who need it
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
All six. Each one is a person your agent needs and cannot be — and the first is
|
|
165
|
-
the one that asks *before* the work rather than about it.
|
|
166
|
-
|
|
167
|
-
## Gating
|
|
168
|
-
|
|
169
|
-
`gate()` is the only primitive whose answer is not yours to decide. The other
|
|
170
|
-
five ask a named person something; this one asks your **organisation's policy**
|
|
171
|
-
whether the action may happen at all, and the answer comes from rules an
|
|
172
|
-
administrator wrote and your code does not see.
|
|
173
|
-
|
|
174
|
-
```ts
|
|
175
|
-
const decision = await deliverd.gate({
|
|
176
|
-
action: "finance.refund",
|
|
177
|
-
externalId: `refund:${order.id}`,
|
|
178
|
-
input: { customer_id: order.customerId, amount: 1240, currency: "GBP" },
|
|
179
|
-
});
|
|
180
|
-
|
|
181
|
-
if (!decision.allowed) return; // denied by a rule, or refused by a person
|
|
182
|
-
await stripe.refunds.create(decision.input);
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
Three answers, one field to branch on:
|
|
186
|
-
|
|
187
|
-
| `status` | `allowed` | What happened |
|
|
188
|
-
|---|---|---|
|
|
189
|
-
| `allowed` | `true` | A rule permitted it. Go. |
|
|
190
|
-
| `denied` | `false` | A rule refused it. `reason` and `rule` say which and why — do not retry it under another name. |
|
|
191
|
-
| `approved` / `rejected` / `expired` / `cancelled` | varies | No rule settled it, so a person was asked. `gate()` waited for them. |
|
|
192
|
-
|
|
193
|
-
**Use `decision.input`, not the object you passed.** It is what the action's
|
|
194
|
-
schema validated and what an approver actually saw. Passing your original works
|
|
195
|
-
right up until somebody edits a value before approving, and then it spends an
|
|
196
|
-
approval for £1200 on a refund of £1240.
|
|
197
|
-
|
|
198
|
-
**`externalId` is required**, which no other call here is. A random
|
|
199
|
-
per-attempt key guards a retried *request*; this guards a retried *decision*. A
|
|
200
|
-
crashed agent re-running its refund step must re-read the answer it already got
|
|
201
|
-
rather than ask a second person about the same money — and no id this library
|
|
202
|
-
could invent would know which two calls are the same attempt. Retrying with the
|
|
203
|
-
same id returns the same decision, with `reused: true`.
|
|
204
|
-
|
|
205
|
-
`wait: false` returns as soon as the decision is raised, pending or not.
|
|
206
|
-
`deliverd.gates.create()` and `deliverd.gates.get(id)` are the same thing with
|
|
207
|
-
the handle exposed, for work that resumes on a webhook rather than in this call.
|
|
208
|
-
|
|
209
|
-
Try it before you have an account: `DELIVERD_DEV_OUTCOME=denied` rehearses a
|
|
210
|
-
policy refusal, which is the branch agents most often forget to write.
|
|
211
|
-
|
|
212
|
-
## Flows
|
|
213
|
-
|
|
214
|
-
A job that takes more than one of them is one job, and a firm asking about it
|
|
215
|
-
afterwards asks about the job — not about approvals in October. A flow is the
|
|
216
|
-
thread that ties them together.
|
|
217
|
-
|
|
218
|
-
```ts
|
|
219
|
-
const flow = await deliverd.flows.resume({
|
|
220
|
-
title: "Q3 close",
|
|
221
|
-
externalId: "close_2026_q3", // so a restart extends this one
|
|
222
|
-
});
|
|
223
|
-
|
|
224
|
-
const { answers } = await flow.collect({ title: "Before I start", questions, respondents });
|
|
225
|
-
const outcome = await flow.review({ title: "Draft pack", reportId, reviewers });
|
|
226
|
-
if (outcome.approved) await deliverd.publish({ title, content, flowId: flow.id });
|
|
227
|
-
|
|
228
|
-
await flow.close();
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
`flow.approve()`, `flow.review()` and `flow.collect()` are the same calls as
|
|
232
|
-
the ones above with the flow already named. That is the whole point of the
|
|
233
|
-
handle: a `flowId` passed by hand at four call sites is one that gets left off
|
|
234
|
-
the fifth, and the step is then missing from the history with nothing to say
|
|
235
|
-
so. Publishing takes `flowId` directly, because a report joins a flow when it
|
|
236
|
-
is first created rather than through a handle.
|
|
237
|
-
|
|
238
|
-
It groups and does nothing else. Nothing waits on a flow, nothing is blocked
|
|
239
|
-
by one, and there are no steps to declare in advance — do the work in the
|
|
240
|
-
order you want it done and name the flow as you go.
|
|
241
|
-
|
|
242
|
-
```ts
|
|
243
|
-
flow.allSettled // nothing in it is waiting on anybody right now
|
|
244
|
-
flow.openCount // how many still are
|
|
245
|
-
flow.timeline // every audited step across all of them, in order
|
|
246
|
-
await flow.refresh()
|
|
247
|
-
await flow.close() // say the work is done; it stops taking new members
|
|
248
|
-
await flow.cancel() // call it off; nothing inside it is cancelled
|
|
249
|
-
await deliverd.flows.list({ status: "open" });
|
|
250
|
-
await deliverd.flows.get(id);
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
`allSettled` is a fact about this moment, not a verdict. You may be about to
|
|
254
|
-
add the next step, so nothing closes a flow but you.
|
|
255
|
-
|
|
256
|
-
## Evidence
|
|
257
|
-
|
|
258
|
-
Show your working. One call assembles the whole record of a piece of work —
|
|
259
|
-
every approval, review and request with who was asked, what they were told and
|
|
260
|
-
what they said, plus the timeline across all of it.
|
|
261
|
-
|
|
262
|
-
```ts
|
|
263
|
-
const pack = await flow.evidence();
|
|
264
|
-
// or, for the deliverable itself:
|
|
265
|
-
const pack = await deliverd.reports.evidence(report.id);
|
|
266
|
-
|
|
267
|
-
pack.steps; // each one with asked[], outcomes[] and its own detail
|
|
268
|
-
pack.timeline; // what happened, in order
|
|
269
|
-
pack.integrity; // what the digest stands for, in the pack's own words
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
A person downloads it as a PDF from the flow or report page; this is the same
|
|
273
|
-
pack as JSON. It needs every read scope, because it contains everything.
|
|
274
|
-
|
|
275
|
-
**Read `integrity` before you quote it.** The digest is over the pack as
|
|
276
|
-
exported, so it detects a file altered after it left. It makes no claim about
|
|
277
|
-
the database — what stands behind the records is that the audit table rejects
|
|
278
|
-
updates and deletes at the database level. That is tamper-evident history, not
|
|
279
|
-
cryptographic immutability, and the pack says so in both directions rather than
|
|
280
|
-
leaving a hash to imply the stronger one.
|
|
281
|
-
|
|
282
|
-
## Collecting
|
|
283
|
-
|
|
284
|
-
`approve()` asks permission, `review()` asks judgement, and this asks for a
|
|
285
|
-
fact — a figure, a date, a choice between options, the sentence only they can
|
|
286
|
-
write.
|
|
287
|
-
|
|
288
|
-
```ts
|
|
289
|
-
const { complete, answers } = await deliverd.collect({
|
|
290
|
-
title: "Before I file the Q3 return",
|
|
291
|
-
respondents: ["finance@firm.example"],
|
|
292
|
-
questions: [
|
|
293
|
-
{ prompt: "Headcount at 30 September", kind: "number" },
|
|
294
|
-
{ prompt: "Any disposals in the quarter?", kind: "boolean" },
|
|
295
|
-
{ prompt: "Which basis?", kind: "choice", options: ["Accrual", "Cash"] },
|
|
296
|
-
],
|
|
297
|
-
});
|
|
298
|
-
|
|
299
|
-
if (!complete) return escalate();
|
|
300
|
-
file(answers["Headcount at 30 September"]);
|
|
301
|
-
```
|
|
302
|
-
|
|
303
|
-
`answers` is keyed by the question you asked, and carries the first submitted
|
|
304
|
-
reply to each. Check `complete` before using it: a request that expired has
|
|
305
|
-
whatever arrived and no more, and what you do without the figure is usually
|
|
306
|
-
not what you do with it. Use `responses` when several people were asked and
|
|
307
|
-
you need all of them rather than the first.
|
|
308
|
-
|
|
309
|
-
Seven kinds of question: `text`, `long_text`, `number`, `date`, `choice`,
|
|
310
|
-
`multi_choice` and `boolean`. Every answer is checked against the kind that
|
|
311
|
-
asked for it before it is stored, and a required question blocks submission —
|
|
312
|
-
so a number field gives you a number, not the string a person typed.
|
|
313
|
-
|
|
314
|
-
There are no file questions. Answers are typed values, and a `file` kind with
|
|
315
|
-
no storage behind it would be a promise the page could not keep.
|
|
316
|
-
|
|
317
|
-
A respondent must be **an active member of your organisation, or a guest the
|
|
318
|
-
organisation already knows**. Anyone else is refused rather than emailed,
|
|
319
|
-
which is what stops an agent reaching an address of its choosing.
|
|
320
|
-
|
|
321
|
-
```ts
|
|
322
|
-
await deliverd.collections.create(input); // ask without waiting
|
|
323
|
-
await deliverd.collections.get(id);
|
|
324
|
-
await deliverd.collections.list({ status: "pending" });
|
|
325
|
-
await deliverd.collections.findByExternalId("q3_close");
|
|
326
|
-
await collection.wait({ onPoll });
|
|
327
|
-
await collection.cancel();
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
There is no method that submits an answer, and no endpoint behind one. People
|
|
331
|
-
answer on the page. They get one reminder before the due date and no more,
|
|
332
|
-
because a nudge that arrives twice teaches people to ignore the first.
|
|
333
|
-
|
|
334
|
-
## Reviewing
|
|
335
|
-
|
|
336
|
-
`approve()` asks permission before you act. `review()` asks whether what you
|
|
337
|
-
already produced is right.
|
|
338
|
-
|
|
339
|
-
```ts
|
|
340
|
-
const outcome = await deliverd.review({
|
|
341
|
-
title: "Q3 board pack",
|
|
342
|
-
reportId: report.id,
|
|
343
|
-
instructions: "Check the figures against the ledger.",
|
|
344
|
-
reviewers: ["partner@firm.example"],
|
|
345
|
-
});
|
|
346
|
-
|
|
347
|
-
if (!outcome.approved) await revise(outcome.verdicts);
|
|
348
|
-
```
|
|
349
|
-
|
|
350
|
-
It resolves on `changes_requested` as well as `approved`, because that is an
|
|
351
|
-
answer — usually the more useful one. `outcome.verdicts` is what each reviewer
|
|
352
|
-
said, and `outcome.threadCount` is how many comments they left anchored to the
|
|
353
|
-
passages they meant. Read those with `deliverd.comments.list(reportId)` and
|
|
354
|
-
turn them into the next version with `deliverd.reports.revisionBrief(reportId)`.
|
|
355
|
-
|
|
356
|
-
A reviewer must be **an active member of your organisation, or a guest who can
|
|
357
|
-
already open the report** — anyone else is refused rather than emailed, which
|
|
358
|
-
is also what stops an agent reaching an address of its choosing. Share the
|
|
359
|
-
report with someone before naming them.
|
|
360
|
-
|
|
361
|
-
You cannot review your own request. One reviewer gives one verdict, and a
|
|
362
|
-
second is refused, because the first one is evidence. `requiredApprovals`
|
|
363
|
-
decides how many approvals settle it; a single `changes_requested` settles it
|
|
364
|
-
regardless, since collecting the rest after somebody has found a problem spends
|
|
365
|
-
their afternoon on a question already answered.
|
|
366
|
-
|
|
367
|
-
```ts
|
|
368
|
-
await deliverd.reviews.create(input); // ask without waiting
|
|
369
|
-
await deliverd.reviews.get(id);
|
|
370
|
-
await deliverd.reviews.list({ status: "pending" });
|
|
371
|
-
await deliverd.reviews.findByExternalId("pack_2026q3");
|
|
372
|
-
await review.wait({ onPoll });
|
|
373
|
-
await review.cancel();
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
There is no method that returns a verdict, and there is no endpoint behind one.
|
|
377
|
-
A verdict is a person's judgement; your key is not a person. They record theirs
|
|
378
|
-
on the page, where they have just read the work.
|
|
379
|
-
|
|
380
|
-
Under `approve()` is the full surface, when you want it:
|
|
381
|
-
|
|
382
|
-
```ts
|
|
383
|
-
await deliverd.approvals.create(input); // ask without waiting
|
|
384
|
-
await deliverd.approvals.get(id);
|
|
385
|
-
await deliverd.approvals.list({ status: "pending" });
|
|
386
|
-
await deliverd.approvals.findByExternalId("deploy_4842");
|
|
387
|
-
await approval.wait({ onQuestion });
|
|
388
|
-
await approval.answer(questionId, "…");
|
|
389
|
-
await approval.cancel(); // withdraw; the row stays
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
Two rules the API enforces and the SDK cannot talk you out of: **an agent
|
|
393
|
-
never decides** — the decision takes a person's session, and there is no
|
|
394
|
-
endpoint for it — and **nobody approves their own request**. Approvers must be
|
|
395
|
-
members of your organisation, named by email or user id; an address that is
|
|
396
|
-
not a member is refused when you create the request, rather than notified into
|
|
397
|
-
nothing.
|
|
398
|
-
|
|
399
|
-
## Publishing
|
|
400
|
-
|
|
401
|
-
The other half of Deliverd: get what your agent wrote to the people who need
|
|
402
|
-
it, at an address that does not change.
|
|
403
|
-
|
|
404
|
-
```ts
|
|
405
|
-
const { report } = await deliverd.reports.publish({
|
|
406
|
-
title: "Q3 board pack",
|
|
407
|
-
content: html,
|
|
408
|
-
audience: "the Finance team",
|
|
409
|
-
});
|
|
410
|
-
console.log(report.url);
|
|
411
|
-
|
|
412
|
-
await deliverd.reports.update(report.id, { content: revised, changeSummary: "…" });
|
|
413
|
-
await deliverd.reports.share(report.id, "sarah@client.example");
|
|
414
|
-
|
|
415
|
-
// Sharing grants access to people the organisation knows. Sending reaches
|
|
416
|
-
// addresses it has never seen, and says something alongside the link.
|
|
417
|
-
await deliverd.reports.send(report.id, {
|
|
418
|
-
to: ["sarah@client.com", "ops@client.com"],
|
|
419
|
-
message: "Final numbers — let me know by Friday if anything looks wrong.",
|
|
420
|
-
});
|
|
421
|
-
```
|
|
422
|
-
|
|
423
|
-
A publishing policy can hold a version for a person's approval, so check
|
|
424
|
-
`result.status`: `published`, `updated` or `pending_approval`. When it is
|
|
425
|
-
held, `result.approval` names the request and nothing is live until somebody
|
|
426
|
-
says so.
|
|
427
|
-
|
|
428
|
-
Also on `reports`: `get`, `list`, `rename`, `archive`, `unarchive`,
|
|
429
|
-
`rollback`, `versions`, `copy`, `analytics`, `putData`, `listData`,
|
|
430
|
-
`deleteData`, `evidence`, `revisionBrief`.
|
|
431
|
-
|
|
432
|
-
And reader feedback:
|
|
433
|
-
|
|
434
|
-
```ts
|
|
435
|
-
// Everything open, across every report — "is anything waiting on me?"
|
|
436
|
-
const waiting = await deliverd.comments.open();
|
|
437
|
-
|
|
438
|
-
const threads = await deliverd.comments.list(reportId);
|
|
439
|
-
await deliverd.comments.resolve(threadId, { note: "Fixed in v4." });
|
|
440
|
-
```
|
|
441
|
-
|
|
442
|
-
## Schedules
|
|
443
|
-
|
|
444
|
-
A schedule says when an agent is asked for a new version. It says nothing
|
|
445
|
-
about who hears about one — publishing emails the report's audience either
|
|
446
|
-
way, and nothing publishes by itself: the agent polls and does the work.
|
|
447
|
-
|
|
448
|
-
```ts
|
|
449
|
-
await deliverd.schedules.create({
|
|
450
|
-
reportId: report.id,
|
|
451
|
-
agentId,
|
|
452
|
-
recurrence: "0 9 * * 5", // Fridays at nine, UTC
|
|
453
|
-
});
|
|
454
|
-
|
|
455
|
-
const due = await deliverd.schedules.list({ dueOnly: true });
|
|
456
|
-
await deliverd.schedules.update(id, { recurrence: "0 9 * * 1" });
|
|
457
|
-
await deliverd.schedules.delete(id);
|
|
458
|
-
```
|
|
459
|
-
|
|
460
|
-
`recurrence` has to have a next occurrence: `0 0 30 2 *` is five well-formed
|
|
461
|
-
fields and a date that never arrives, and is refused rather than stored.
|
|
462
|
-
|
|
463
|
-
An **agent key cannot write here**. A schedule is an instruction *to* an
|
|
464
|
-
agent, so setting one is a person's decision — use a user key. Reading is
|
|
465
|
-
open to both, and an agent sees only the schedules addressed to it.
|
|
466
|
-
|
|
467
|
-
## Webhooks
|
|
468
|
-
|
|
469
|
-
Rather than polling, take the decision as it happens. Verify first — a
|
|
470
|
-
receiver that skips this accepts anything anyone posts at the URL.
|
|
471
|
-
|
|
472
|
-
```ts
|
|
473
|
-
import { constructEvent } from "@deliverd/sdk";
|
|
474
|
-
|
|
475
|
-
app.post("/webhooks/deliverd", express.raw({ type: "application/json" }), (req, res) => {
|
|
476
|
-
const event = constructEvent(
|
|
477
|
-
process.env.DELIVERD_WEBHOOK_SECRET!,
|
|
478
|
-
req.body.toString("utf8"), // the raw body, not a re-encoded object
|
|
479
|
-
req.header("deliverd-signature")
|
|
480
|
-
);
|
|
481
|
-
|
|
482
|
-
if (event.event === "approval.approved") {
|
|
483
|
-
// event.data.approvalId, .externalId, .decidedBy, .note
|
|
484
|
-
}
|
|
485
|
-
res.sendStatus(200);
|
|
486
|
-
});
|
|
487
|
-
```
|
|
488
|
-
|
|
489
|
-
`constructEvent` throws if the signature does not verify; `verifySignature`
|
|
490
|
-
returns a boolean if you would rather branch. The scheme is Stripe's — a
|
|
491
|
-
timestamp and an HMAC in one header, the timestamp inside the signed material,
|
|
492
|
-
five minutes of tolerance — so anything you have written before will work too.
|
|
493
|
-
|
|
494
|
-
## Approving with changes
|
|
495
|
-
|
|
496
|
-
Send what you will act on as `input`, and say which fields a person may
|
|
497
|
-
correct. The approver sees the values and can fix a field instead of
|
|
498
|
-
rejecting the whole thing; you run with what they approved.
|
|
499
|
-
|
|
500
|
-
```ts
|
|
501
|
-
const decision = await deliverd.approve({
|
|
502
|
-
title: "Refund £420 to Acme",
|
|
503
|
-
input: { orderId: "1042", amount: 420 },
|
|
504
|
-
editableFields: ["amount"],
|
|
505
|
-
});
|
|
506
|
-
if (decision.approved) await refund(decision.input!); // corrections included
|
|
507
|
-
// decision.changes: [{ field: "amount", from: 420, to: 300 }]
|
|
508
|
-
```
|
|
509
|
-
|
|
510
|
-
`decision.input` is null unless it was approved, so it is never the proposal
|
|
511
|
-
by accident. With the Claude Agent SDK adapter, pass
|
|
512
|
-
`editable: (tool) => (tool === "refund" ? ["amount"] : [])` and the tool runs
|
|
513
|
-
with the approved input.
|
|
514
|
-
|
|
515
|
-
## Callbacks
|
|
516
|
-
|
|
517
|
-
A webhook tells one endpoint about everything in the organisation. A callback
|
|
518
|
-
is per request: pass `callbackUrl` and Deliverd POSTs that request's outcome
|
|
519
|
-
there, signed with a secret only it uses, retrying if your endpoint is down.
|
|
520
|
-
|
|
521
|
-
```ts
|
|
522
|
-
const approval = await deliverd.approvals.create({
|
|
523
|
-
title: "Refund £420 to Acme",
|
|
524
|
-
approvers: ["finance"],
|
|
525
|
-
callbackUrl: "https://agent.example.com/hooks/deliverd",
|
|
526
|
-
});
|
|
527
|
-
await store.put(approval.id, approval.callbackSecret); // handed over once
|
|
528
|
-
|
|
529
|
-
// …and where it lands:
|
|
530
|
-
const envelope = constructCallback(secret, rawBody, req.header("deliverd-signature"));
|
|
531
|
-
// envelope.event: "approval.approved" | "approval.rejected" | "approval.expired" | "approval.question" | …
|
|
532
|
-
```
|
|
533
|
-
|
|
534
|
-
For code that should not hold a process open while a person decides: a
|
|
535
|
-
serverless function, a durable workflow, a paused graph.
|
|
536
|
-
|
|
537
|
-
## Inside your agent framework
|
|
538
|
-
|
|
539
|
-
`@deliverd/sdk/adapters` plugs Deliverd into the approval hook each framework
|
|
540
|
-
already has. A person approves the tool call from the email, Slack or Teams;
|
|
541
|
-
a decline reaches the model as their reason; a retried call never asks twice.
|
|
542
|
-
|
|
543
|
-
**Claude Agent SDK**
|
|
544
|
-
|
|
545
|
-
```ts
|
|
546
|
-
import { deliverdCanUseTool } from "@deliverd/sdk/adapters";
|
|
547
|
-
|
|
548
|
-
query({ prompt, options: { canUseTool: deliverdCanUseTool({ deliverd, when: (tool) => tool === "Bash" }) } });
|
|
549
|
-
```
|
|
550
|
-
|
|
551
|
-
**Vercel AI SDK**
|
|
552
|
-
|
|
553
|
-
```ts
|
|
554
|
-
import { deliverdToolApproval } from "@deliverd/sdk/adapters";
|
|
555
|
-
|
|
556
|
-
generateText({ model, tools, prompt, toolApproval: deliverdToolApproval({ deliverd, approvers: ["finance"] }) });
|
|
557
|
-
```
|
|
558
|
-
|
|
559
|
-
**OpenAI Agents SDK** — mark tools `needsApproval: true`, then:
|
|
560
|
-
|
|
561
|
-
```ts
|
|
562
|
-
import { runWithDeliverdApprovals } from "@deliverd/sdk/adapters";
|
|
563
|
-
|
|
564
|
-
const result = await runWithDeliverdApprovals((input) => run(agent, input), "Refund order 1042", { deliverd });
|
|
565
|
-
```
|
|
566
|
-
|
|
567
|
-
**LangGraph** — pause the graph rather than a process, and resume it from the callback:
|
|
568
|
-
|
|
569
|
-
```ts
|
|
570
|
-
import { approveInGraph, resumeFromCallback } from "@deliverd/sdk/adapters";
|
|
571
|
-
|
|
572
|
-
// in a node
|
|
573
|
-
const decision = await approveInGraph(deliverd, {
|
|
574
|
-
interrupt, threadId: config.configurable.thread_id, step: "refund",
|
|
575
|
-
title: "Refund £420 to Acme", callbackUrl: "https://agent.example.com/hooks/deliverd",
|
|
576
|
-
});
|
|
577
|
-
|
|
578
|
-
// in the callback handler
|
|
579
|
-
const resume = resumeFromCallback(constructCallback(secret, rawBody, signature));
|
|
580
|
-
if (resume) await graph.invoke(new Command({ resume: resume.value }), { configurable: { thread_id: resume.threadId } });
|
|
581
|
-
```
|
|
582
|
-
|
|
583
|
-
The decision is always read back from Deliverd, never taken from the resume
|
|
584
|
-
value, so a stray resume cannot approve anything.
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
## Lists
|
|
588
|
-
|
|
589
|
-
`list()` gives you all of them. It follows the API's cursor until there is no
|
|
590
|
-
next page, so `.length` is the real count rather than a page size that happens
|
|
591
|
-
to look like one:
|
|
592
|
-
|
|
593
|
-
```ts
|
|
594
|
-
const waiting = await deliverd.approvals.list({ status: "pending" });
|
|
595
|
-
```
|
|
596
|
-
|
|
597
|
-
Ask for a `limit` and you get exactly that page instead — one request, one
|
|
598
|
-
page. When you want to drive the paging yourself, `listPage()` hands back the
|
|
599
|
-
cursor:
|
|
600
|
-
|
|
601
|
-
```ts
|
|
602
|
-
let cursor: string | undefined;
|
|
603
|
-
do {
|
|
604
|
-
const page = await deliverd.approvals.listPage({ limit: 100, cursor });
|
|
605
|
-
for (const approval of page.items) { /* … */ }
|
|
606
|
-
cursor = page.nextCursor ?? undefined;
|
|
607
|
-
} while (cursor);
|
|
608
|
-
```
|
|
609
|
-
|
|
610
|
-
The reason `list()` defaults to everything rather than to one page: a full page
|
|
611
|
-
and a complete list look identical, so a method called `list` that quietly
|
|
612
|
-
returns the first fifty is a wrong answer shaped like a right one.
|
|
613
|
-
|
|
614
|
-
## Errors
|
|
615
|
-
|
|
616
|
-
An error is part of the interface, so it says what happened and the one thing
|
|
617
|
-
to do next:
|
|
618
|
-
|
|
619
|
-
```
|
|
620
|
-
No approver could be found for this request.
|
|
621
|
-
Everyone in `approvers` must be an active member of your organisation, named
|
|
622
|
-
by email or user id. Invite them first, or leave `approvers` out and your
|
|
623
|
-
owners and admins decide.
|
|
624
|
-
```
|
|
625
|
-
|
|
626
|
-
Every failure is a `DeliverdError` with the API's `code`, the HTTP `status`,
|
|
627
|
-
the `hint` as its own property, and `isAuth`, `isNotFound`, `isRateLimit` and
|
|
628
|
-
`isConflict` for the cases worth branching on. Rate limits and 5xx are retried
|
|
629
|
-
for you; a 4xx is not, because it will be just as wrong a second later.
|
|
630
|
-
|
|
631
|
-
## Options
|
|
632
|
-
|
|
633
|
-
```ts
|
|
634
|
-
new Deliverd({
|
|
635
|
-
apiKey: process.env.DELIVERD_API_KEY, // default: DELIVERD_API_KEY
|
|
636
|
-
baseUrl: "https://deliverd.dev", // default: DELIVERD_BASE_URL
|
|
637
|
-
mode: "live", // default: DELIVERD_MODE
|
|
638
|
-
maxRetries: 3,
|
|
639
|
-
timeout: 30_000, // per request, not per wait
|
|
640
|
-
});
|
|
641
|
-
```
|
|
642
|
-
|
|
643
|
-
Zero dependencies. Node 20 or later.
|
|
644
|
-
|
|
645
|
-
## Also
|
|
646
|
-
|
|
647
|
-
- The same walkthrough as a page, if you would rather read it there:
|
|
648
|
-
<https://deliverd.dev/quickstart>
|
|
649
|
-
- The API reference: <https://deliverd.dev/docs/api>
|
|
650
|
-
- MCP, if your agent speaks it rather than TypeScript:
|
|
651
|
-
<https://deliverd.dev/connect>
|
|
652
|
-
- The CLI, for a terminal or a CI job: `npm install -g deliverd`
|
|
653
|
-
|
|
654
|
-
MIT.
|
|
1
|
+
# @deliverd/sdk
|
|
2
|
+
|
|
3
|
+
You build the action. Deliverd handles the human.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install @deliverd/sdk
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import { deliverd } from "@deliverd/sdk";
|
|
11
|
+
|
|
12
|
+
const decision = await deliverd.approve({ title: "Deploy to production" });
|
|
13
|
+
|
|
14
|
+
if (decision.approved) await deploy();
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
That is the integration. What it stands in for: an approval page, the emails
|
|
18
|
+
and the reminders, identity and single sign-on, who is allowed to decide, a
|
|
19
|
+
table to keep it in, an audit trail, and the dashboard somebody uses to do it.
|
|
20
|
+
None of that is yours to build.
|
|
21
|
+
|
|
22
|
+
Your approver gets an email and a notification, opens a page that works on a
|
|
23
|
+
phone, and approves, rejects with a reason, or asks your agent a question.
|
|
24
|
+
Every step is on the record.
|
|
25
|
+
|
|
26
|
+
## Before you have an account
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { Deliverd } from "@deliverd/sdk";
|
|
30
|
+
|
|
31
|
+
const deliverd = new Deliverd({ mode: "development" });
|
|
32
|
+
const decision = await deliverd.approve({ title: "Deploy to production" });
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
No key, no network, nobody interrupted. It prints what the approver would have
|
|
36
|
+
seen and answers instantly:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
┌─ Deliverd · development mode ─────────────────────────
|
|
40
|
+
│ Refund £1,240 to Acme
|
|
41
|
+
│ Duplicate charge on invoice 4821.
|
|
42
|
+
│ Risk: high
|
|
43
|
+
│ ✓ Within the refund limit
|
|
44
|
+
│ To: finance@example.com
|
|
45
|
+
│
|
|
46
|
+
│ Simulating: approved
|
|
47
|
+
└───────────────────────────────────────────────────────
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
All four things that can happen are one word away, including the one people
|
|
51
|
+
forget to write:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
new Deliverd({ mode: "development", development: { outcome: "rejected" } });
|
|
55
|
+
new Deliverd({ mode: "development", development: { outcome: "timeout" } });
|
|
56
|
+
new Deliverd({ mode: "development", development: { outcome: "question" } });
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Or flip a whole test suite from the command line with
|
|
60
|
+
`DELIVERD_DEV_OUTCOME=rejected`. Development mode swaps out the network and
|
|
61
|
+
nothing else, so the code it exercises is the code that will run in
|
|
62
|
+
production — the same retries, the same errors, the same waiting.
|
|
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
|
+
|
|
68
|
+
## Configuration
|
|
69
|
+
|
|
70
|
+
There is none. `new Deliverd()` reads `DELIVERD_API_KEY`, and
|
|
71
|
+
`import { deliverd }` does not even need that line. Everything below has a
|
|
72
|
+
default that works:
|
|
73
|
+
|
|
74
|
+
| | Default |
|
|
75
|
+
|---|---|
|
|
76
|
+
| Who decides | Your organisation's owners and admins, unless you name `approvers` |
|
|
77
|
+
| Expiry | 24 hours, so a wait always ends |
|
|
78
|
+
| Notifications | Email and in-app, to whoever has to decide |
|
|
79
|
+
| Retries | Transient failures and rate limits, honouring `Retry-After` |
|
|
80
|
+
| Audit | On. Every request, question and decision, with the actor |
|
|
81
|
+
| Correlation id | Generated per request and sent with it |
|
|
82
|
+
| Webhook signing | Already signed; verify with `constructEvent` |
|
|
83
|
+
| Lists | `list()` returns every row; it follows the cursor so you do not have to |
|
|
84
|
+
|
|
85
|
+
## Progressive depth
|
|
86
|
+
|
|
87
|
+
Level one is the five lines above. Level two adds context, which is what the
|
|
88
|
+
approver reads before deciding:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
await deliverd.approve({
|
|
92
|
+
title: "Deploy release 4.2 to production",
|
|
93
|
+
description: "142 commits since 4.1. All checks green.",
|
|
94
|
+
risk: "high",
|
|
95
|
+
factors: [
|
|
96
|
+
{ label: "All checks green", status: "ok" },
|
|
97
|
+
{ label: "Touches the payments path", status: "warning", detail: "3 files under /billing" },
|
|
98
|
+
],
|
|
99
|
+
links: [{ label: "The diff", url: "https://github.com/…/compare/4.1...4.2" }],
|
|
100
|
+
approvers: ["dave@example.com"],
|
|
101
|
+
expiresIn: "4h",
|
|
102
|
+
externalId: "deploy_4842",
|
|
103
|
+
});
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
`externalId` is your own reference. Pass one and a restarted agent reuses the
|
|
107
|
+
request it already made rather than asking a second time.
|
|
108
|
+
|
|
109
|
+
## Answering the approver
|
|
110
|
+
|
|
111
|
+
The thing that makes this more than a pause button: a person can ask your
|
|
112
|
+
agent a question from the approval page, and your agent can answer it without
|
|
113
|
+
anyone leaving what they are doing.
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
await approval.wait({
|
|
117
|
+
onQuestion: async (question) => {
|
|
118
|
+
// Return a string and it is posted as the answer; return null to leave
|
|
119
|
+
// it for a person.
|
|
120
|
+
return await agent.ask(question.question);
|
|
121
|
+
},
|
|
122
|
+
});
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Without a handler the question simply sits there — which is correct, because
|
|
126
|
+
the approver is waiting on an answer and nothing should move until they get
|
|
127
|
+
one or decide anyway.
|
|
128
|
+
|
|
129
|
+
## Waiting
|
|
130
|
+
|
|
131
|
+
`wait()` polls, backing off from two seconds to a minute with jitter, so a
|
|
132
|
+
hundred agents started by the same cron do not arrive together. It resolves
|
|
133
|
+
when the request settles, **including on a rejection** — a refusal is an
|
|
134
|
+
answer, and `if (approval.approved)` is the line that should follow.
|
|
135
|
+
|
|
136
|
+
It throws only when the wait itself failed:
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
try {
|
|
140
|
+
await approval.wait({ timeout: 30 * 60_000 });
|
|
141
|
+
} catch (err) {
|
|
142
|
+
if (err instanceof DeliverdTimeoutError) {
|
|
143
|
+
// Nobody decided in time. The request is still open at approval.url.
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Give every request an `expiresAt` or every wait a `timeout`. A request with
|
|
149
|
+
neither can be waited on for ever, which is what `await` means.
|
|
150
|
+
|
|
151
|
+
`wait()` also takes an `AbortSignal`, and `onPoll` for a progress line.
|
|
152
|
+
|
|
153
|
+
## The primitives
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
await deliverd.gate({ action, input, externalId }); // may I? — your organisation answers
|
|
157
|
+
await deliverd.approve({ title }); // ask permission, and wait for the answer
|
|
158
|
+
await deliverd.review({ title, reportId, reviewers }); // ask whether it is right
|
|
159
|
+
await deliverd.collect({ title, questions, respondents }); // ask for what you lack
|
|
160
|
+
await deliverd.confirm({ title }); // a yes or no on something small → boolean
|
|
161
|
+
await deliverd.publish({ title, content }); // get the work to the people who need it
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
All six. Each one is a person your agent needs and cannot be — and the first is
|
|
165
|
+
the one that asks *before* the work rather than about it.
|
|
166
|
+
|
|
167
|
+
## Gating
|
|
168
|
+
|
|
169
|
+
`gate()` is the only primitive whose answer is not yours to decide. The other
|
|
170
|
+
five ask a named person something; this one asks your **organisation's policy**
|
|
171
|
+
whether the action may happen at all, and the answer comes from rules an
|
|
172
|
+
administrator wrote and your code does not see.
|
|
173
|
+
|
|
174
|
+
```ts
|
|
175
|
+
const decision = await deliverd.gate({
|
|
176
|
+
action: "finance.refund",
|
|
177
|
+
externalId: `refund:${order.id}`,
|
|
178
|
+
input: { customer_id: order.customerId, amount: 1240, currency: "GBP" },
|
|
179
|
+
});
|
|
180
|
+
|
|
181
|
+
if (!decision.allowed) return; // denied by a rule, or refused by a person
|
|
182
|
+
await stripe.refunds.create(decision.input);
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Three answers, one field to branch on:
|
|
186
|
+
|
|
187
|
+
| `status` | `allowed` | What happened |
|
|
188
|
+
|---|---|---|
|
|
189
|
+
| `allowed` | `true` | A rule permitted it. Go. |
|
|
190
|
+
| `denied` | `false` | A rule refused it. `reason` and `rule` say which and why — do not retry it under another name. |
|
|
191
|
+
| `approved` / `rejected` / `expired` / `cancelled` | varies | No rule settled it, so a person was asked. `gate()` waited for them. |
|
|
192
|
+
|
|
193
|
+
**Use `decision.input`, not the object you passed.** It is what the action's
|
|
194
|
+
schema validated and what an approver actually saw. Passing your original works
|
|
195
|
+
right up until somebody edits a value before approving, and then it spends an
|
|
196
|
+
approval for £1200 on a refund of £1240.
|
|
197
|
+
|
|
198
|
+
**`externalId` is required**, which no other call here is. A random
|
|
199
|
+
per-attempt key guards a retried *request*; this guards a retried *decision*. A
|
|
200
|
+
crashed agent re-running its refund step must re-read the answer it already got
|
|
201
|
+
rather than ask a second person about the same money — and no id this library
|
|
202
|
+
could invent would know which two calls are the same attempt. Retrying with the
|
|
203
|
+
same id returns the same decision, with `reused: true`.
|
|
204
|
+
|
|
205
|
+
`wait: false` returns as soon as the decision is raised, pending or not.
|
|
206
|
+
`deliverd.gates.create()` and `deliverd.gates.get(id)` are the same thing with
|
|
207
|
+
the handle exposed, for work that resumes on a webhook rather than in this call.
|
|
208
|
+
|
|
209
|
+
Try it before you have an account: `DELIVERD_DEV_OUTCOME=denied` rehearses a
|
|
210
|
+
policy refusal, which is the branch agents most often forget to write.
|
|
211
|
+
|
|
212
|
+
## Flows
|
|
213
|
+
|
|
214
|
+
A job that takes more than one of them is one job, and a firm asking about it
|
|
215
|
+
afterwards asks about the job — not about approvals in October. A flow is the
|
|
216
|
+
thread that ties them together.
|
|
217
|
+
|
|
218
|
+
```ts
|
|
219
|
+
const flow = await deliverd.flows.resume({
|
|
220
|
+
title: "Q3 close",
|
|
221
|
+
externalId: "close_2026_q3", // so a restart extends this one
|
|
222
|
+
});
|
|
223
|
+
|
|
224
|
+
const { answers } = await flow.collect({ title: "Before I start", questions, respondents });
|
|
225
|
+
const outcome = await flow.review({ title: "Draft pack", reportId, reviewers });
|
|
226
|
+
if (outcome.approved) await deliverd.publish({ title, content, flowId: flow.id });
|
|
227
|
+
|
|
228
|
+
await flow.close();
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
`flow.approve()`, `flow.review()` and `flow.collect()` are the same calls as
|
|
232
|
+
the ones above with the flow already named. That is the whole point of the
|
|
233
|
+
handle: a `flowId` passed by hand at four call sites is one that gets left off
|
|
234
|
+
the fifth, and the step is then missing from the history with nothing to say
|
|
235
|
+
so. Publishing takes `flowId` directly, because a report joins a flow when it
|
|
236
|
+
is first created rather than through a handle.
|
|
237
|
+
|
|
238
|
+
It groups and does nothing else. Nothing waits on a flow, nothing is blocked
|
|
239
|
+
by one, and there are no steps to declare in advance — do the work in the
|
|
240
|
+
order you want it done and name the flow as you go.
|
|
241
|
+
|
|
242
|
+
```ts
|
|
243
|
+
flow.allSettled // nothing in it is waiting on anybody right now
|
|
244
|
+
flow.openCount // how many still are
|
|
245
|
+
flow.timeline // every audited step across all of them, in order
|
|
246
|
+
await flow.refresh()
|
|
247
|
+
await flow.close() // say the work is done; it stops taking new members
|
|
248
|
+
await flow.cancel() // call it off; nothing inside it is cancelled
|
|
249
|
+
await deliverd.flows.list({ status: "open" });
|
|
250
|
+
await deliverd.flows.get(id);
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
`allSettled` is a fact about this moment, not a verdict. You may be about to
|
|
254
|
+
add the next step, so nothing closes a flow but you.
|
|
255
|
+
|
|
256
|
+
## Evidence
|
|
257
|
+
|
|
258
|
+
Show your working. One call assembles the whole record of a piece of work —
|
|
259
|
+
every approval, review and request with who was asked, what they were told and
|
|
260
|
+
what they said, plus the timeline across all of it.
|
|
261
|
+
|
|
262
|
+
```ts
|
|
263
|
+
const pack = await flow.evidence();
|
|
264
|
+
// or, for the deliverable itself:
|
|
265
|
+
const pack = await deliverd.reports.evidence(report.id);
|
|
266
|
+
|
|
267
|
+
pack.steps; // each one with asked[], outcomes[] and its own detail
|
|
268
|
+
pack.timeline; // what happened, in order
|
|
269
|
+
pack.integrity; // what the digest stands for, in the pack's own words
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
A person downloads it as a PDF from the flow or report page; this is the same
|
|
273
|
+
pack as JSON. It needs every read scope, because it contains everything.
|
|
274
|
+
|
|
275
|
+
**Read `integrity` before you quote it.** The digest is over the pack as
|
|
276
|
+
exported, so it detects a file altered after it left. It makes no claim about
|
|
277
|
+
the database — what stands behind the records is that the audit table rejects
|
|
278
|
+
updates and deletes at the database level. That is tamper-evident history, not
|
|
279
|
+
cryptographic immutability, and the pack says so in both directions rather than
|
|
280
|
+
leaving a hash to imply the stronger one.
|
|
281
|
+
|
|
282
|
+
## Collecting
|
|
283
|
+
|
|
284
|
+
`approve()` asks permission, `review()` asks judgement, and this asks for a
|
|
285
|
+
fact — a figure, a date, a choice between options, the sentence only they can
|
|
286
|
+
write.
|
|
287
|
+
|
|
288
|
+
```ts
|
|
289
|
+
const { complete, answers } = await deliverd.collect({
|
|
290
|
+
title: "Before I file the Q3 return",
|
|
291
|
+
respondents: ["finance@firm.example"],
|
|
292
|
+
questions: [
|
|
293
|
+
{ prompt: "Headcount at 30 September", kind: "number" },
|
|
294
|
+
{ prompt: "Any disposals in the quarter?", kind: "boolean" },
|
|
295
|
+
{ prompt: "Which basis?", kind: "choice", options: ["Accrual", "Cash"] },
|
|
296
|
+
],
|
|
297
|
+
});
|
|
298
|
+
|
|
299
|
+
if (!complete) return escalate();
|
|
300
|
+
file(answers["Headcount at 30 September"]);
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
`answers` is keyed by the question you asked, and carries the first submitted
|
|
304
|
+
reply to each. Check `complete` before using it: a request that expired has
|
|
305
|
+
whatever arrived and no more, and what you do without the figure is usually
|
|
306
|
+
not what you do with it. Use `responses` when several people were asked and
|
|
307
|
+
you need all of them rather than the first.
|
|
308
|
+
|
|
309
|
+
Seven kinds of question: `text`, `long_text`, `number`, `date`, `choice`,
|
|
310
|
+
`multi_choice` and `boolean`. Every answer is checked against the kind that
|
|
311
|
+
asked for it before it is stored, and a required question blocks submission —
|
|
312
|
+
so a number field gives you a number, not the string a person typed.
|
|
313
|
+
|
|
314
|
+
There are no file questions. Answers are typed values, and a `file` kind with
|
|
315
|
+
no storage behind it would be a promise the page could not keep.
|
|
316
|
+
|
|
317
|
+
A respondent must be **an active member of your organisation, or a guest the
|
|
318
|
+
organisation already knows**. Anyone else is refused rather than emailed,
|
|
319
|
+
which is what stops an agent reaching an address of its choosing.
|
|
320
|
+
|
|
321
|
+
```ts
|
|
322
|
+
await deliverd.collections.create(input); // ask without waiting
|
|
323
|
+
await deliverd.collections.get(id);
|
|
324
|
+
await deliverd.collections.list({ status: "pending" });
|
|
325
|
+
await deliverd.collections.findByExternalId("q3_close");
|
|
326
|
+
await collection.wait({ onPoll });
|
|
327
|
+
await collection.cancel();
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
There is no method that submits an answer, and no endpoint behind one. People
|
|
331
|
+
answer on the page. They get one reminder before the due date and no more,
|
|
332
|
+
because a nudge that arrives twice teaches people to ignore the first.
|
|
333
|
+
|
|
334
|
+
## Reviewing
|
|
335
|
+
|
|
336
|
+
`approve()` asks permission before you act. `review()` asks whether what you
|
|
337
|
+
already produced is right.
|
|
338
|
+
|
|
339
|
+
```ts
|
|
340
|
+
const outcome = await deliverd.review({
|
|
341
|
+
title: "Q3 board pack",
|
|
342
|
+
reportId: report.id,
|
|
343
|
+
instructions: "Check the figures against the ledger.",
|
|
344
|
+
reviewers: ["partner@firm.example"],
|
|
345
|
+
});
|
|
346
|
+
|
|
347
|
+
if (!outcome.approved) await revise(outcome.verdicts);
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
It resolves on `changes_requested` as well as `approved`, because that is an
|
|
351
|
+
answer — usually the more useful one. `outcome.verdicts` is what each reviewer
|
|
352
|
+
said, and `outcome.threadCount` is how many comments they left anchored to the
|
|
353
|
+
passages they meant. Read those with `deliverd.comments.list(reportId)` and
|
|
354
|
+
turn them into the next version with `deliverd.reports.revisionBrief(reportId)`.
|
|
355
|
+
|
|
356
|
+
A reviewer must be **an active member of your organisation, or a guest who can
|
|
357
|
+
already open the report** — anyone else is refused rather than emailed, which
|
|
358
|
+
is also what stops an agent reaching an address of its choosing. Share the
|
|
359
|
+
report with someone before naming them.
|
|
360
|
+
|
|
361
|
+
You cannot review your own request. One reviewer gives one verdict, and a
|
|
362
|
+
second is refused, because the first one is evidence. `requiredApprovals`
|
|
363
|
+
decides how many approvals settle it; a single `changes_requested` settles it
|
|
364
|
+
regardless, since collecting the rest after somebody has found a problem spends
|
|
365
|
+
their afternoon on a question already answered.
|
|
366
|
+
|
|
367
|
+
```ts
|
|
368
|
+
await deliverd.reviews.create(input); // ask without waiting
|
|
369
|
+
await deliverd.reviews.get(id);
|
|
370
|
+
await deliverd.reviews.list({ status: "pending" });
|
|
371
|
+
await deliverd.reviews.findByExternalId("pack_2026q3");
|
|
372
|
+
await review.wait({ onPoll });
|
|
373
|
+
await review.cancel();
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
There is no method that returns a verdict, and there is no endpoint behind one.
|
|
377
|
+
A verdict is a person's judgement; your key is not a person. They record theirs
|
|
378
|
+
on the page, where they have just read the work.
|
|
379
|
+
|
|
380
|
+
Under `approve()` is the full surface, when you want it:
|
|
381
|
+
|
|
382
|
+
```ts
|
|
383
|
+
await deliverd.approvals.create(input); // ask without waiting
|
|
384
|
+
await deliverd.approvals.get(id);
|
|
385
|
+
await deliverd.approvals.list({ status: "pending" });
|
|
386
|
+
await deliverd.approvals.findByExternalId("deploy_4842");
|
|
387
|
+
await approval.wait({ onQuestion });
|
|
388
|
+
await approval.answer(questionId, "…");
|
|
389
|
+
await approval.cancel(); // withdraw; the row stays
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
Two rules the API enforces and the SDK cannot talk you out of: **an agent
|
|
393
|
+
never decides** — the decision takes a person's session, and there is no
|
|
394
|
+
endpoint for it — and **nobody approves their own request**. Approvers must be
|
|
395
|
+
members of your organisation, named by email or user id; an address that is
|
|
396
|
+
not a member is refused when you create the request, rather than notified into
|
|
397
|
+
nothing.
|
|
398
|
+
|
|
399
|
+
## Publishing
|
|
400
|
+
|
|
401
|
+
The other half of Deliverd: get what your agent wrote to the people who need
|
|
402
|
+
it, at an address that does not change.
|
|
403
|
+
|
|
404
|
+
```ts
|
|
405
|
+
const { report } = await deliverd.reports.publish({
|
|
406
|
+
title: "Q3 board pack",
|
|
407
|
+
content: html,
|
|
408
|
+
audience: "the Finance team",
|
|
409
|
+
});
|
|
410
|
+
console.log(report.url);
|
|
411
|
+
|
|
412
|
+
await deliverd.reports.update(report.id, { content: revised, changeSummary: "…" });
|
|
413
|
+
await deliverd.reports.share(report.id, "sarah@client.example");
|
|
414
|
+
|
|
415
|
+
// Sharing grants access to people the organisation knows. Sending reaches
|
|
416
|
+
// addresses it has never seen, and says something alongside the link.
|
|
417
|
+
await deliverd.reports.send(report.id, {
|
|
418
|
+
to: ["sarah@client.com", "ops@client.com"],
|
|
419
|
+
message: "Final numbers — let me know by Friday if anything looks wrong.",
|
|
420
|
+
});
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
A publishing policy can hold a version for a person's approval, so check
|
|
424
|
+
`result.status`: `published`, `updated` or `pending_approval`. When it is
|
|
425
|
+
held, `result.approval` names the request and nothing is live until somebody
|
|
426
|
+
says so.
|
|
427
|
+
|
|
428
|
+
Also on `reports`: `get`, `list`, `rename`, `archive`, `unarchive`,
|
|
429
|
+
`rollback`, `versions`, `copy`, `analytics`, `putData`, `listData`,
|
|
430
|
+
`deleteData`, `evidence`, `revisionBrief`.
|
|
431
|
+
|
|
432
|
+
And reader feedback:
|
|
433
|
+
|
|
434
|
+
```ts
|
|
435
|
+
// Everything open, across every report — "is anything waiting on me?"
|
|
436
|
+
const waiting = await deliverd.comments.open();
|
|
437
|
+
|
|
438
|
+
const threads = await deliverd.comments.list(reportId);
|
|
439
|
+
await deliverd.comments.resolve(threadId, { note: "Fixed in v4." });
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
## Schedules
|
|
443
|
+
|
|
444
|
+
A schedule says when an agent is asked for a new version. It says nothing
|
|
445
|
+
about who hears about one — publishing emails the report's audience either
|
|
446
|
+
way, and nothing publishes by itself: the agent polls and does the work.
|
|
447
|
+
|
|
448
|
+
```ts
|
|
449
|
+
await deliverd.schedules.create({
|
|
450
|
+
reportId: report.id,
|
|
451
|
+
agentId,
|
|
452
|
+
recurrence: "0 9 * * 5", // Fridays at nine, UTC
|
|
453
|
+
});
|
|
454
|
+
|
|
455
|
+
const due = await deliverd.schedules.list({ dueOnly: true });
|
|
456
|
+
await deliverd.schedules.update(id, { recurrence: "0 9 * * 1" });
|
|
457
|
+
await deliverd.schedules.delete(id);
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
`recurrence` has to have a next occurrence: `0 0 30 2 *` is five well-formed
|
|
461
|
+
fields and a date that never arrives, and is refused rather than stored.
|
|
462
|
+
|
|
463
|
+
An **agent key cannot write here**. A schedule is an instruction *to* an
|
|
464
|
+
agent, so setting one is a person's decision — use a user key. Reading is
|
|
465
|
+
open to both, and an agent sees only the schedules addressed to it.
|
|
466
|
+
|
|
467
|
+
## Webhooks
|
|
468
|
+
|
|
469
|
+
Rather than polling, take the decision as it happens. Verify first — a
|
|
470
|
+
receiver that skips this accepts anything anyone posts at the URL.
|
|
471
|
+
|
|
472
|
+
```ts
|
|
473
|
+
import { constructEvent } from "@deliverd/sdk";
|
|
474
|
+
|
|
475
|
+
app.post("/webhooks/deliverd", express.raw({ type: "application/json" }), (req, res) => {
|
|
476
|
+
const event = constructEvent(
|
|
477
|
+
process.env.DELIVERD_WEBHOOK_SECRET!,
|
|
478
|
+
req.body.toString("utf8"), // the raw body, not a re-encoded object
|
|
479
|
+
req.header("deliverd-signature")
|
|
480
|
+
);
|
|
481
|
+
|
|
482
|
+
if (event.event === "approval.approved") {
|
|
483
|
+
// event.data.approvalId, .externalId, .decidedBy, .note
|
|
484
|
+
}
|
|
485
|
+
res.sendStatus(200);
|
|
486
|
+
});
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
`constructEvent` throws if the signature does not verify; `verifySignature`
|
|
490
|
+
returns a boolean if you would rather branch. The scheme is Stripe's — a
|
|
491
|
+
timestamp and an HMAC in one header, the timestamp inside the signed material,
|
|
492
|
+
five minutes of tolerance — so anything you have written before will work too.
|
|
493
|
+
|
|
494
|
+
## Approving with changes
|
|
495
|
+
|
|
496
|
+
Send what you will act on as `input`, and say which fields a person may
|
|
497
|
+
correct. The approver sees the values and can fix a field instead of
|
|
498
|
+
rejecting the whole thing; you run with what they approved.
|
|
499
|
+
|
|
500
|
+
```ts
|
|
501
|
+
const decision = await deliverd.approve({
|
|
502
|
+
title: "Refund £420 to Acme",
|
|
503
|
+
input: { orderId: "1042", amount: 420 },
|
|
504
|
+
editableFields: ["amount"],
|
|
505
|
+
});
|
|
506
|
+
if (decision.approved) await refund(decision.input!); // corrections included
|
|
507
|
+
// decision.changes: [{ field: "amount", from: 420, to: 300 }]
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
`decision.input` is null unless it was approved, so it is never the proposal
|
|
511
|
+
by accident. With the Claude Agent SDK adapter, pass
|
|
512
|
+
`editable: (tool) => (tool === "refund" ? ["amount"] : [])` and the tool runs
|
|
513
|
+
with the approved input.
|
|
514
|
+
|
|
515
|
+
## Callbacks
|
|
516
|
+
|
|
517
|
+
A webhook tells one endpoint about everything in the organisation. A callback
|
|
518
|
+
is per request: pass `callbackUrl` and Deliverd POSTs that request's outcome
|
|
519
|
+
there, signed with a secret only it uses, retrying if your endpoint is down.
|
|
520
|
+
|
|
521
|
+
```ts
|
|
522
|
+
const approval = await deliverd.approvals.create({
|
|
523
|
+
title: "Refund £420 to Acme",
|
|
524
|
+
approvers: ["finance"],
|
|
525
|
+
callbackUrl: "https://agent.example.com/hooks/deliverd",
|
|
526
|
+
});
|
|
527
|
+
await store.put(approval.id, approval.callbackSecret); // handed over once
|
|
528
|
+
|
|
529
|
+
// …and where it lands:
|
|
530
|
+
const envelope = constructCallback(secret, rawBody, req.header("deliverd-signature"));
|
|
531
|
+
// envelope.event: "approval.approved" | "approval.rejected" | "approval.expired" | "approval.question" | …
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
For code that should not hold a process open while a person decides: a
|
|
535
|
+
serverless function, a durable workflow, a paused graph.
|
|
536
|
+
|
|
537
|
+
## Inside your agent framework
|
|
538
|
+
|
|
539
|
+
`@deliverd/sdk/adapters` plugs Deliverd into the approval hook each framework
|
|
540
|
+
already has. A person approves the tool call from the email, Slack or Teams;
|
|
541
|
+
a decline reaches the model as their reason; a retried call never asks twice.
|
|
542
|
+
|
|
543
|
+
**Claude Agent SDK**
|
|
544
|
+
|
|
545
|
+
```ts
|
|
546
|
+
import { deliverdCanUseTool } from "@deliverd/sdk/adapters";
|
|
547
|
+
|
|
548
|
+
query({ prompt, options: { canUseTool: deliverdCanUseTool({ deliverd, when: (tool) => tool === "Bash" }) } });
|
|
549
|
+
```
|
|
550
|
+
|
|
551
|
+
**Vercel AI SDK**
|
|
552
|
+
|
|
553
|
+
```ts
|
|
554
|
+
import { deliverdToolApproval } from "@deliverd/sdk/adapters";
|
|
555
|
+
|
|
556
|
+
generateText({ model, tools, prompt, toolApproval: deliverdToolApproval({ deliverd, approvers: ["finance"] }) });
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
**OpenAI Agents SDK** — mark tools `needsApproval: true`, then:
|
|
560
|
+
|
|
561
|
+
```ts
|
|
562
|
+
import { runWithDeliverdApprovals } from "@deliverd/sdk/adapters";
|
|
563
|
+
|
|
564
|
+
const result = await runWithDeliverdApprovals((input) => run(agent, input), "Refund order 1042", { deliverd });
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
**LangGraph** — pause the graph rather than a process, and resume it from the callback:
|
|
568
|
+
|
|
569
|
+
```ts
|
|
570
|
+
import { approveInGraph, resumeFromCallback } from "@deliverd/sdk/adapters";
|
|
571
|
+
|
|
572
|
+
// in a node
|
|
573
|
+
const decision = await approveInGraph(deliverd, {
|
|
574
|
+
interrupt, threadId: config.configurable.thread_id, step: "refund",
|
|
575
|
+
title: "Refund £420 to Acme", callbackUrl: "https://agent.example.com/hooks/deliverd",
|
|
576
|
+
});
|
|
577
|
+
|
|
578
|
+
// in the callback handler
|
|
579
|
+
const resume = resumeFromCallback(constructCallback(secret, rawBody, signature));
|
|
580
|
+
if (resume) await graph.invoke(new Command({ resume: resume.value }), { configurable: { thread_id: resume.threadId } });
|
|
581
|
+
```
|
|
582
|
+
|
|
583
|
+
The decision is always read back from Deliverd, never taken from the resume
|
|
584
|
+
value, so a stray resume cannot approve anything.
|
|
585
|
+
|
|
586
|
+
|
|
587
|
+
## Lists
|
|
588
|
+
|
|
589
|
+
`list()` gives you all of them. It follows the API's cursor until there is no
|
|
590
|
+
next page, so `.length` is the real count rather than a page size that happens
|
|
591
|
+
to look like one:
|
|
592
|
+
|
|
593
|
+
```ts
|
|
594
|
+
const waiting = await deliverd.approvals.list({ status: "pending" });
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
Ask for a `limit` and you get exactly that page instead — one request, one
|
|
598
|
+
page. When you want to drive the paging yourself, `listPage()` hands back the
|
|
599
|
+
cursor:
|
|
600
|
+
|
|
601
|
+
```ts
|
|
602
|
+
let cursor: string | undefined;
|
|
603
|
+
do {
|
|
604
|
+
const page = await deliverd.approvals.listPage({ limit: 100, cursor });
|
|
605
|
+
for (const approval of page.items) { /* … */ }
|
|
606
|
+
cursor = page.nextCursor ?? undefined;
|
|
607
|
+
} while (cursor);
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
The reason `list()` defaults to everything rather than to one page: a full page
|
|
611
|
+
and a complete list look identical, so a method called `list` that quietly
|
|
612
|
+
returns the first fifty is a wrong answer shaped like a right one.
|
|
613
|
+
|
|
614
|
+
## Errors
|
|
615
|
+
|
|
616
|
+
An error is part of the interface, so it says what happened and the one thing
|
|
617
|
+
to do next:
|
|
618
|
+
|
|
619
|
+
```
|
|
620
|
+
No approver could be found for this request.
|
|
621
|
+
Everyone in `approvers` must be an active member of your organisation, named
|
|
622
|
+
by email or user id. Invite them first, or leave `approvers` out and your
|
|
623
|
+
owners and admins decide.
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
Every failure is a `DeliverdError` with the API's `code`, the HTTP `status`,
|
|
627
|
+
the `hint` as its own property, and `isAuth`, `isNotFound`, `isRateLimit` and
|
|
628
|
+
`isConflict` for the cases worth branching on. Rate limits and 5xx are retried
|
|
629
|
+
for you; a 4xx is not, because it will be just as wrong a second later.
|
|
630
|
+
|
|
631
|
+
## Options
|
|
632
|
+
|
|
633
|
+
```ts
|
|
634
|
+
new Deliverd({
|
|
635
|
+
apiKey: process.env.DELIVERD_API_KEY, // default: DELIVERD_API_KEY
|
|
636
|
+
baseUrl: "https://deliverd.dev", // default: DELIVERD_BASE_URL
|
|
637
|
+
mode: "live", // default: DELIVERD_MODE
|
|
638
|
+
maxRetries: 3,
|
|
639
|
+
timeout: 30_000, // per request, not per wait
|
|
640
|
+
});
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
Zero dependencies. Node 20 or later.
|
|
644
|
+
|
|
645
|
+
## Also
|
|
646
|
+
|
|
647
|
+
- The same walkthrough as a page, if you would rather read it there:
|
|
648
|
+
<https://deliverd.dev/quickstart>
|
|
649
|
+
- The API reference: <https://deliverd.dev/docs/api>
|
|
650
|
+
- MCP, if your agent speaks it rather than TypeScript:
|
|
651
|
+
<https://deliverd.dev/connect>
|
|
652
|
+
- The CLI, for a terminal or a CI job: `npm install -g deliverd`
|
|
653
|
+
|
|
654
|
+
MIT.
|