@deliverd/sdk 0.8.1 → 0.9.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 (63) 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 +11 -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/messages.d.ts.map +1 -1
  35. package/dist/messages.js +84 -5
  36. package/dist/released.d.ts +1 -1
  37. package/dist/released.d.ts.map +1 -1
  38. package/dist/released.js +864 -0
  39. package/dist/reviews.d.ts +8 -0
  40. package/dist/reviews.d.ts.map +1 -1
  41. package/dist/reviews.js +11 -1
  42. package/dist/types.d.ts +73 -1
  43. package/dist/types.d.ts.map +1 -1
  44. package/dist/webhooks.d.ts +15 -1
  45. package/dist/webhooks.d.ts.map +1 -1
  46. package/dist/webhooks.js +13 -0
  47. package/package.json +5 -1
  48. package/src/adapters/ai-sdk.ts +59 -0
  49. package/src/adapters/claude-agent-sdk.ts +90 -0
  50. package/src/adapters/index.ts +23 -0
  51. package/src/adapters/langgraph.ts +202 -0
  52. package/src/adapters/openai-agents.ts +112 -0
  53. package/src/adapters/shared.ts +179 -0
  54. package/src/approvals.ts +21 -1
  55. package/src/collections.ts +12 -1
  56. package/src/dev.ts +19 -0
  57. package/src/gates.ts +1 -0
  58. package/src/index.ts +1 -0
  59. package/src/messages.ts +84 -5
  60. package/src/released.ts +865 -0
  61. package/src/reviews.ts +12 -1
  62. package/src/types.ts +84 -1
  63. 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,13 @@ 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[];
68
73
  /** Whether a rule decided this or a person did. */
69
74
  basis: "policy" | "human";
70
75
  reason: string | null;
@@ -91,12 +96,22 @@ export interface GateDecision {
91
96
  status: GateStatus;
92
97
  reason: string | null;
93
98
  rule: string | null;
99
+ /** What to execute with, corrections included. */
94
100
  input: Record<string, unknown>;
101
+ /** What the approver changed. Empty unless they did. */
102
+ changes: FieldChange[];
95
103
  id: string;
96
104
  approvalUrl: string | null;
97
105
  gate: unknown;
98
106
  }
99
107
 
108
+ /** One field an approver corrected before approving. */
109
+ export interface FieldChange {
110
+ field: string;
111
+ from: unknown;
112
+ to: unknown;
113
+ }
114
+
100
115
  /** One line of evidence, as the approval page shows it. */
101
116
  export interface ApprovalFactor {
102
117
  label: string;
@@ -130,6 +145,14 @@ export interface ApprovalData {
130
145
  reportId: string | null;
131
146
  externalId: string | null;
132
147
  metadata: Record<string, unknown>;
148
+ /** What you proposed to run with, unchanged. */
149
+ input: Record<string, unknown> | null;
150
+ /** Which fields of it the approver may correct. */
151
+ editableFields: string[];
152
+ /** What to run with once approved: `input` with any corrections. Null until then. */
153
+ approvedInput: Record<string, unknown> | null;
154
+ /** What the approver changed. */
155
+ changes: FieldChange[];
133
156
  requestedBy: string;
134
157
  approvers: string[];
135
158
  /**
@@ -188,7 +211,23 @@ export interface CreateApprovalInput {
188
211
  * siblings set this for you.
189
212
  */
190
213
  flowId?: string;
214
+ /**
215
+ * Where to POST the outcome when a person answers, instead of polling:
216
+ * HTTPS, and a public address. The call that makes the request returns the
217
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
218
+ */
219
+ callbackUrl?: string;
191
220
  metadata?: Record<string, unknown>;
221
+ /**
222
+ * The arguments you will run with if this is approved, shown to the
223
+ * approver. The decision's `input` is what to actually run with.
224
+ */
225
+ input?: Record<string, unknown>;
226
+ /**
227
+ * Fields of `input` the approver may correct before approving: strings,
228
+ * numbers and true/false. Omitted, it is approve or reject only.
229
+ */
230
+ editableFields?: string[];
192
231
  }
193
232
 
194
233
  /**
@@ -214,6 +253,14 @@ export type Decision = {
214
253
  id: string;
215
254
  /** The page they decided on. Worth logging. */
216
255
  url: string;
256
+ /**
257
+ * What to run with, when you sent an `input` and it was approved: yours,
258
+ * with any corrections the approver made. Null otherwise — never run the
259
+ * proposal when this is null.
260
+ */
261
+ input: Record<string, unknown> | null;
262
+ /** What the approver changed. Empty when they approved it as proposed. */
263
+ changes: FieldChange[];
217
264
  /** The request itself, for anything the fields above do not name. */
218
265
  approval: unknown;
219
266
  };
@@ -506,6 +553,12 @@ export interface CreateReviewInput {
506
553
  * siblings set this for you.
507
554
  */
508
555
  flowId?: string;
556
+ /**
557
+ * Where to POST the outcome when a person answers, instead of polling:
558
+ * HTTPS, and a public address. The call that makes the request returns the
559
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
560
+ */
561
+ callbackUrl?: string;
509
562
  metadata?: Record<string, unknown>;
510
563
  }
511
564
 
@@ -623,6 +676,12 @@ export interface CreateCollectionInput {
623
676
  * siblings set this for you.
624
677
  */
625
678
  flowId?: string;
679
+ /**
680
+ * Where to POST the outcome when a person answers, instead of polling:
681
+ * HTTPS, and a public address. The call that makes the request returns the
682
+ * secret its callbacks are signed with (`callbackSecret` on the handle).
683
+ */
684
+ callbackUrl?: string;
626
685
  metadata?: Record<string, unknown>;
627
686
  }
628
687
 
@@ -836,3 +895,27 @@ export interface EvidencePack {
836
895
  recordsAreInsertOnly: boolean;
837
896
  };
838
897
  }
898
+
899
+ /**
900
+ * What arrives at a request's `callbackUrl`.
901
+ *
902
+ * `data` is the same object an organisation webhook carries for the event.
903
+ * `approval.question` means the approver asked something and is waiting on
904
+ * your answer (`answerQuestion`); every other event is the request settling.
905
+ */
906
+ export interface CallbackEnvelope {
907
+ event:
908
+ | "approval.approved"
909
+ | "approval.rejected"
910
+ | "approval.expired"
911
+ | "approval.question"
912
+ | "review.approved"
913
+ | "review.changes_requested"
914
+ | "review.expired"
915
+ | "collection.completed"
916
+ | "collection.expired";
917
+ sentAt: string;
918
+ requestType: "approval" | "review" | "collection";
919
+ requestId: string;
920
+ data: Record<string, unknown>;
921
+ }
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;