@deliverd/sdk 0.8.2 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +92 -0
  2. package/dist/adapters/ai-sdk.d.ts +48 -0
  3. package/dist/adapters/ai-sdk.d.ts.map +1 -0
  4. package/dist/adapters/ai-sdk.js +12 -0
  5. package/dist/adapters/claude-agent-sdk.d.ts +55 -0
  6. package/dist/adapters/claude-agent-sdk.d.ts.map +1 -0
  7. package/dist/adapters/claude-agent-sdk.js +24 -0
  8. package/dist/adapters/index.d.ts +19 -0
  9. package/dist/adapters/index.d.ts.map +1 -0
  10. package/dist/adapters/index.js +13 -0
  11. package/dist/adapters/langgraph.d.ts +145 -0
  12. package/dist/adapters/langgraph.d.ts.map +1 -0
  13. package/dist/adapters/langgraph.js +69 -0
  14. package/dist/adapters/openai-agents.d.ts +68 -0
  15. package/dist/adapters/openai-agents.d.ts.map +1 -0
  16. package/dist/adapters/openai-agents.js +55 -0
  17. package/dist/adapters/shared.d.ts +91 -0
  18. package/dist/adapters/shared.d.ts.map +1 -0
  19. package/dist/adapters/shared.js +98 -0
  20. package/dist/approvals.d.ts +15 -1
  21. package/dist/approvals.d.ts.map +1 -1
  22. package/dist/approvals.js +19 -1
  23. package/dist/collections.d.ts +8 -0
  24. package/dist/collections.d.ts.map +1 -1
  25. package/dist/collections.js +11 -1
  26. package/dist/dev.d.ts +6 -0
  27. package/dist/dev.d.ts.map +1 -1
  28. package/dist/dev.js +13 -0
  29. package/dist/gates.d.ts.map +1 -1
  30. package/dist/gates.js +1 -0
  31. package/dist/index.d.ts +1 -1
  32. package/dist/index.d.ts.map +1 -1
  33. package/dist/index.js +1 -1
  34. package/dist/released.d.ts +1 -1
  35. package/dist/released.d.ts.map +1 -1
  36. package/dist/released.js +910 -0
  37. package/dist/reviews.d.ts +8 -0
  38. package/dist/reviews.d.ts.map +1 -1
  39. package/dist/reviews.js +11 -1
  40. package/dist/types.d.ts +93 -1
  41. package/dist/types.d.ts.map +1 -1
  42. package/dist/webhooks.d.ts +15 -1
  43. package/dist/webhooks.d.ts.map +1 -1
  44. package/dist/webhooks.js +13 -0
  45. package/package.json +5 -1
  46. package/src/adapters/ai-sdk.ts +59 -0
  47. package/src/adapters/claude-agent-sdk.ts +90 -0
  48. package/src/adapters/index.ts +23 -0
  49. package/src/adapters/langgraph.ts +202 -0
  50. package/src/adapters/openai-agents.ts +112 -0
  51. package/src/adapters/shared.ts +179 -0
  52. package/src/approvals.ts +21 -1
  53. package/src/collections.ts +12 -1
  54. package/src/dev.ts +21 -0
  55. package/src/gates.ts +1 -0
  56. package/src/index.ts +1 -0
  57. package/src/released.ts +910 -0
  58. package/src/reviews.ts +12 -1
  59. package/src/types.ts +96 -1
  60. package/src/webhooks.ts +20 -1
package/src/reviews.ts CHANGED
@@ -45,6 +45,15 @@ export class Review {
45
45
  private data: ReviewData
46
46
  ) {}
47
47
 
48
+ /**
49
+ * The secret this request's callbacks are signed with, when you gave a
50
+ * `callbackUrl`. Only on the handle `create()` returned — the API hands it
51
+ * over once and never again — so keep it with whatever will receive the
52
+ * callback, and check each one with
53
+ * `deliverd.webhooks.constructCallback(callbackSecret, rawBody, signature)`.
54
+ */
55
+ callbackSecret: string | null = null;
56
+
48
57
  get id(): string { return this.data.id; }
49
58
  get status(): ReviewData["status"] { return this.data.status; }
50
59
  /** The page the reviewer reads and decides on. */
@@ -163,7 +172,9 @@ export class Reviews {
163
172
  body: input,
164
173
  signal,
165
174
  });
166
- return new Review(this.http, data);
175
+ const created = new Review(this.http, data);
176
+ created.callbackSecret = (data as ReviewData & { callbackSecret?: string }).callbackSecret ?? null;
177
+ return created;
167
178
  }
168
179
 
169
180
  async get(id: string, signal?: AbortSignal): Promise<Review> {
package/src/types.ts CHANGED
@@ -63,8 +63,19 @@ export interface GateData {
63
63
  status: GateStatus;
64
64
  /** The one to branch on: a rule permitted it, or a person agreed to it. */
65
65
  allowed: boolean;
66
- /** The input as the action's schema validated it — what to execute with. */
66
+ /**
67
+ * What to execute with: the input as the action's schema validated it, or
68
+ * the approver's correction of it when they approved with changes.
69
+ */
67
70
  input: Record<string, unknown>;
71
+ /** What the approver changed in it. Empty unless they did. */
72
+ changes: FieldChange[];
73
+ /**
74
+ * What the organisation's ethics rules asked whoever decides to weigh, as
75
+ * they read when this was asked. Empty when nothing matched. A flagged
76
+ * request is approved with a written reason, never from a sign-in-free link.
77
+ */
78
+ concerns: { principle: string; rule: string; concern: string }[];
68
79
  /** Whether a rule decided this or a person did. */
69
80
  basis: "policy" | "human";
70
81
  reason: string | null;
@@ -91,12 +102,22 @@ export interface GateDecision {
91
102
  status: GateStatus;
92
103
  reason: string | null;
93
104
  rule: string | null;
105
+ /** What to execute with, corrections included. */
94
106
  input: Record<string, unknown>;
107
+ /** What the approver changed. Empty unless they did. */
108
+ changes: FieldChange[];
95
109
  id: string;
96
110
  approvalUrl: string | null;
97
111
  gate: unknown;
98
112
  }
99
113
 
114
+ /** One field an approver corrected before approving. */
115
+ export interface FieldChange {
116
+ field: string;
117
+ from: unknown;
118
+ to: unknown;
119
+ }
120
+
100
121
  /** One line of evidence, as the approval page shows it. */
101
122
  export interface ApprovalFactor {
102
123
  label: string;
@@ -130,6 +151,20 @@ export interface ApprovalData {
130
151
  reportId: string | null;
131
152
  externalId: string | null;
132
153
  metadata: Record<string, unknown>;
154
+ /** What you proposed to run with, unchanged. */
155
+ input: Record<string, unknown> | null;
156
+ /** Which fields of it the approver may correct. */
157
+ editableFields: string[];
158
+ /** What to run with once approved: `input` with any corrections. Null until then. */
159
+ approvedInput: Record<string, unknown> | null;
160
+ /** What the approver changed. */
161
+ changes: FieldChange[];
162
+ /**
163
+ * What the organisation's ethics rules asked whoever decides to weigh, as
164
+ * they read when this was asked. Empty when nothing matched. A flagged
165
+ * request is approved with a written reason, never from a sign-in-free link.
166
+ */
167
+ concerns: { principle: string; rule: string; concern: string }[];
133
168
  requestedBy: string;
134
169
  approvers: string[];
135
170
  /**
@@ -188,7 +223,23 @@ export interface CreateApprovalInput {
188
223
  * siblings set this for you.
189
224
  */
190
225
  flowId?: string;
226
+ /**
227
+ * Where to POST the outcome when a person answers, instead of polling:
228
+ * HTTPS, and a public address. The call that makes the request returns the
229
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
230
+ */
231
+ callbackUrl?: string;
191
232
  metadata?: Record<string, unknown>;
233
+ /**
234
+ * The arguments you will run with if this is approved, shown to the
235
+ * approver. The decision's `input` is what to actually run with.
236
+ */
237
+ input?: Record<string, unknown>;
238
+ /**
239
+ * Fields of `input` the approver may correct before approving: strings,
240
+ * numbers and true/false. Omitted, it is approve or reject only.
241
+ */
242
+ editableFields?: string[];
192
243
  }
193
244
 
194
245
  /**
@@ -214,6 +265,14 @@ export type Decision = {
214
265
  id: string;
215
266
  /** The page they decided on. Worth logging. */
216
267
  url: string;
268
+ /**
269
+ * What to run with, when you sent an `input` and it was approved: yours,
270
+ * with any corrections the approver made. Null otherwise — never run the
271
+ * proposal when this is null.
272
+ */
273
+ input: Record<string, unknown> | null;
274
+ /** What the approver changed. Empty when they approved it as proposed. */
275
+ changes: FieldChange[];
217
276
  /** The request itself, for anything the fields above do not name. */
218
277
  approval: unknown;
219
278
  };
@@ -506,6 +565,12 @@ export interface CreateReviewInput {
506
565
  * siblings set this for you.
507
566
  */
508
567
  flowId?: string;
568
+ /**
569
+ * Where to POST the outcome when a person answers, instead of polling:
570
+ * HTTPS, and a public address. The call that makes the request returns the
571
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
572
+ */
573
+ callbackUrl?: string;
509
574
  metadata?: Record<string, unknown>;
510
575
  }
511
576
 
@@ -623,6 +688,12 @@ export interface CreateCollectionInput {
623
688
  * siblings set this for you.
624
689
  */
625
690
  flowId?: string;
691
+ /**
692
+ * Where to POST the outcome when a person answers, instead of polling:
693
+ * HTTPS, and a public address. The call that makes the request returns the
694
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
695
+ */
696
+ callbackUrl?: string;
626
697
  metadata?: Record<string, unknown>;
627
698
  }
628
699
 
@@ -836,3 +907,27 @@ export interface EvidencePack {
836
907
  recordsAreInsertOnly: boolean;
837
908
  };
838
909
  }
910
+
911
+ /**
912
+ * What arrives at a request's `callbackUrl`.
913
+ *
914
+ * `data` is the same object an organisation webhook carries for the event.
915
+ * `approval.question` means the approver asked something and is waiting on
916
+ * your answer (`answerQuestion`); every other event is the request settling.
917
+ */
918
+ export interface CallbackEnvelope {
919
+ event:
920
+ | "approval.approved"
921
+ | "approval.rejected"
922
+ | "approval.expired"
923
+ | "approval.question"
924
+ | "review.approved"
925
+ | "review.changes_requested"
926
+ | "review.expired"
927
+ | "collection.completed"
928
+ | "collection.expired";
929
+ sentAt: string;
930
+ requestType: "approval" | "review" | "collection";
931
+ requestId: string;
932
+ data: Record<string, unknown>;
933
+ }
package/src/webhooks.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { createHmac, timingSafeEqual } from "node:crypto";
2
2
  import { DeliverdError } from "./errors.js";
3
- import type { WebhookEvent } from "./types.js";
3
+ import type { CallbackEnvelope, WebhookEvent } from "./types.js";
4
4
 
5
5
  /**
6
6
  * Verifying what Deliverd sends you.
@@ -89,9 +89,28 @@ export function constructEvent(
89
89
  }
90
90
  }
91
91
 
92
+ /**
93
+ * Verify and parse a per-request callback: what Deliverd POSTs to the
94
+ * `callbackUrl` you gave when you asked, when a person answers.
95
+ *
96
+ * Signed exactly as a webhook is, with the request's own `callbackSecret`
97
+ * (returned once, by the call that made the request) in place of an
98
+ * endpoint's. Throws on a body that does not verify, for the same reason
99
+ * `constructEvent` does.
100
+ */
101
+ export function constructCallback(
102
+ callbackSecret: string,
103
+ body: string,
104
+ header: string | null | undefined,
105
+ options: { now?: number; toleranceSeconds?: number } = {}
106
+ ): CallbackEnvelope {
107
+ return constructEvent(callbackSecret, body, header, options) as unknown as CallbackEnvelope;
108
+ }
109
+
92
110
  export class Webhooks {
93
111
  verifySignature = verifySignature;
94
112
  constructEvent = constructEvent;
113
+ constructCallback = constructCallback;
95
114
  readonly signatureHeader = SIGNATURE_HEADER;
96
115
  readonly eventHeader = EVENT_HEADER;
97
116
  readonly deliveryHeader = DELIVERY_HEADER;