@deliverd/sdk 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/index.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { HttpClient, type ClientOptions } from "./http.js";
2
2
  import { Approvals, FAST_POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
3
+ import { Gates, type GateOptions } from "./gates.js";
3
4
  import { Comments, Reports, Schedules } from "./reports.js";
4
5
  import { Reviews, type ReviewWaitOptions } from "./reviews.js";
5
6
  import { Collections, type CollectWaitOptions } from "./collections.js";
@@ -14,12 +15,14 @@ import type {
14
15
  CreateCollectionInput,
15
16
  CreateReviewInput,
16
17
  Decision,
18
+ GateDecision,
17
19
  PublishReportInput,
18
20
  PublishResult,
19
21
  ReviewOutcome,
20
22
  } from "./types.js";
21
23
 
22
24
  export { Approval, Approvals, POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
25
+ export { Gate, Gates, type GateOptions, type GateWaitOptions } from "./gates.js";
23
26
  export { Comments, Reports, Schedules } from "./reports.js";
24
27
  export { Review, Reviews, type ReviewWaitOptions } from "./reviews.js";
25
28
  export { Collection, Collections, type CollectWaitOptions } from "./collections.js";
@@ -133,6 +136,7 @@ export interface CollectOptions extends Omit<CreateCollectionInput, "expiresAt">
133
136
  */
134
137
  export class Deliverd {
135
138
  readonly approvals: Approvals;
139
+ readonly gates: Gates;
136
140
  readonly reviews: Reviews;
137
141
  readonly collections: Collections;
138
142
  readonly flows: Flows;
@@ -157,6 +161,7 @@ export class Deliverd {
157
161
  });
158
162
 
159
163
  this.approvals = new Approvals(this.http);
164
+ this.gates = new Gates(this.http);
160
165
  this.reviews = new Reviews(this.http);
161
166
  this.collections = new Collections(this.http);
162
167
  /*
@@ -224,6 +229,60 @@ export class Deliverd {
224
229
  return settled.toDecision();
225
230
  }
226
231
 
232
+ /**
233
+ * Ask whether to act, and wait if a person has to decide.
234
+ *
235
+ * The other primitives ask a person to look at work already done. This one
236
+ * asks first, and the answer comes from **policy the developer does not
237
+ * own** — which is the whole point: what needs a human is an organisation's
238
+ * decision, not a line in your code. Most calls never reach a person at all,
239
+ * because a rule already settles them.
240
+ *
241
+ * ```ts
242
+ * const decision = await deliverd.gate({
243
+ * action: "finance.refund",
244
+ * externalId: `refund:${order.id}`,
245
+ * input: { customer_id: order.customerId, amount: 1240, currency: "GBP" },
246
+ * });
247
+ * if (!decision.allowed) return;
248
+ * await stripe.refunds.create(decision.input);
249
+ * ```
250
+ *
251
+ * **Execute with `decision.input`, not your own object.** It is what the
252
+ * action's schema validated and what an approver actually saw. Passing the
253
+ * original works right up until somebody edits a value before approving, and
254
+ * then it spends an approval for £1200 on a refund of £1240.
255
+ *
256
+ * It does not throw on a refusal — a no is an answer, and `if
257
+ * (decision.allowed)` is the line that follows. It throws when the action is
258
+ * not registered, when the input does not match its schema, or when the wait
259
+ * itself failed.
260
+ *
261
+ * `wait: false` returns a pending decision immediately; `deliverd.gates`
262
+ * is the same thing with the handle exposed.
263
+ */
264
+ async gate(options: GateOptions): Promise<GateDecision> {
265
+ const { action, timeout, onPoll, signal, wait, pollIntervals, ...rest } = options;
266
+ const gate = await this.gates.create({ actionId: action, ...rest }, signal);
267
+
268
+ /*
269
+ * No wait when the caller said not to, and none when there is nothing to
270
+ * wait for — a rule that allowed or denied it has already answered, which
271
+ * is the common case and must not cost a poll.
272
+ */
273
+ if (wait === false || !gate.pending) return gate.toDecision();
274
+
275
+ const settled = await gate.wait({
276
+ onPoll,
277
+ signal,
278
+ /* The same reasoning as `approve()`: an imaginary approver is instant, so
279
+ * a wait still running after a moment is one that never settles. */
280
+ timeout: durationOrUndefined(timeout) ?? (this.development ? 2_000 : undefined),
281
+ ...(pollIntervals ? { pollIntervals } : this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
282
+ });
283
+ return settled.toDecision();
284
+ }
285
+
227
286
  /**
228
287
  * A yes or no on something small: same mechanism, lower ceremony.
229
288
  *