@deliverd/sdk 0.10.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/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.