@deliverd/sdk 0.40.0 → 0.42.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/gates.ts CHANGED
@@ -6,6 +6,7 @@ import type {
6
6
  GateAgentRef,
7
7
  GateData,
8
8
  GateDecision,
9
+ GateOnUnavailable,
9
10
  RecordExecutionInput,
10
11
  } from "./types.js";
11
12
 
@@ -76,6 +77,14 @@ export interface GateOptions extends GateWaitOptions {
76
77
  environment?: string;
77
78
  reason?: string;
78
79
  flowId?: string;
80
+ model?: string;
81
+ traceparent?: string;
82
+ /**
83
+ * What to do when Deliverd cannot be reached: `throw` (default), `deny` or
84
+ * `allow`. Choose per action: `deny` for a payment, `allow` for a low-risk
85
+ * read you would rather not stall. Only network failures and 5xx count.
86
+ */
87
+ onUnavailable?: GateOnUnavailable;
79
88
  /**
80
89
  * Whether to block when policy sends it to a person. Default true.
81
90
  *
@@ -367,3 +376,32 @@ export class Gates {
367
376
  return new Gate(this.http, data);
368
377
  }
369
378
  }
379
+
380
+ /**
381
+ * Whether an error means Deliverd could not be reached, as opposed to an
382
+ * answer: a network failure or a 5xx. An abort, a timed-out wait and every 4xx
383
+ * are not, so `onUnavailable` never hides a bug or a refusal.
384
+ */
385
+ export function isUnavailable(err: unknown, signal?: AbortSignal): boolean {
386
+ if (!(err instanceof DeliverdError) || err instanceof DeliverdTimeoutError) return false;
387
+ if (signal?.aborted || err.code === "aborted" || err.code === "no_api_key") return false;
388
+ return err.status === 0 || err.status >= 500;
389
+ }
390
+
391
+ /** The decision `onUnavailable` gives when Deliverd could not be reached. */
392
+ export function unavailableDecision(mode: Exclude<GateOnUnavailable, "throw">, input: Record<string, unknown>, err: DeliverdError): GateDecision {
393
+ const allowed = mode === "allow";
394
+ return {
395
+ allowed,
396
+ status: allowed ? "allowed" : "denied",
397
+ reason: `Deliverd could not be reached (${err.code}), so onUnavailable: "${mode}" answered.`,
398
+ rule: null,
399
+ input,
400
+ changes: [],
401
+ id: "",
402
+ approvalUrl: null,
403
+ decisionToken: null,
404
+ gate: null,
405
+ unavailable: true,
406
+ };
407
+ }
package/src/index.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { HttpClient, type ClientOptions } from "./http.js";
2
2
  import { Approvals, DecisionSessions, FAST_POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
3
- import { Gates, type GateOptions } from "./gates.js";
3
+ import { Gates, isUnavailable, unavailableDecision, type GateOptions } from "./gates.js";
4
+ import { Events } from "./events.js";
4
5
  import { Comments, Reports, Schedules } from "./reports.js";
5
6
  import { Reviews, type ReviewWaitOptions } from "./reviews.js";
6
7
  import { Collections, type CollectWaitOptions } from "./collections.js";
@@ -29,6 +30,17 @@ import type {
29
30
 
30
31
  export { Approval, Approvals, DecisionSessions, POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
31
32
  export { Gate, Gates, type GateOptions, type GateWaitOptions } from "./gates.js";
33
+ export {
34
+ Events,
35
+ type Decided,
36
+ type EventArguments,
37
+ type EventDefinition,
38
+ type EventName,
39
+ type EventOccurrence,
40
+ type PollInput,
41
+ type PollResult,
42
+ type WatchOptions,
43
+ } from "./events.js";
32
44
  export { Comments, Reports, Schedules } from "./reports.js";
33
45
  export { Review, Reviews, type ReviewWaitOptions } from "./reviews.js";
34
46
  export { Collection, Collections, type CollectWaitOptions } from "./collections.js";
@@ -198,6 +210,8 @@ export class Deliverd {
198
210
  readonly webhookEndpoints: WebhookEndpoints;
199
211
  /** Check a gate's signed yes where the action happens, before it happens. */
200
212
  readonly decisionTokens: DecisionTokens;
213
+ /** Be told instead of asking: MCP Events (approval.decided, gate.decided...) over REST. */
214
+ readonly events: Events;
201
215
  readonly http: HttpClient;
202
216
  /** Whether an imaginary approver is deciding these. */
203
217
  readonly development: boolean;
@@ -235,6 +249,7 @@ export class Deliverd {
235
249
  this.webhooks = new Webhooks();
236
250
  this.webhookEndpoints = new WebhookEndpoints(this.http);
237
251
  this.decisionTokens = new DecisionTokens(this.http.baseUrl, options.fetch);
252
+ this.events = new Events(this.http);
238
253
  }
239
254
 
240
255
  /**
@@ -321,10 +336,24 @@ export class Deliverd {
321
336
  *
322
337
  * `wait: false` returns a pending decision immediately; `deliverd.gates`
323
338
  * is the same thing with the handle exposed.
339
+ *
340
+ * `onUnavailable` decides what happens when Deliverd cannot be reached (a
341
+ * network failure or a 5xx, never a 4xx): `throw` by default, or `deny` or
342
+ * `allow` per action. It applies to the first check only, never to a wait
343
+ * for a person. Such a decision has `unavailable: true`, an empty id
344
+ * and no decision token, and nothing is recorded in Deliverd.
324
345
  */
325
346
  async gate(options: GateOptions): Promise<GateDecision> {
326
- const { action, timeout, onPoll, signal, wait, pollIntervals, ...rest } = options;
327
- const gate = await this.gates.create({ actionId: action, ...rest }, signal);
347
+ const { action, timeout, onPoll, signal, wait, pollIntervals, onUnavailable = "throw", ...rest } = options;
348
+ let gate;
349
+ try {
350
+ gate = await this.gates.create({ actionId: action, ...rest }, signal);
351
+ } catch (err) {
352
+ /* Only the first check. Once a person is deciding, an outage during the
353
+ * wait is never turned into a yes or a no on their behalf. */
354
+ if (onUnavailable === "throw" || !isUnavailable(err, signal)) throw err;
355
+ return unavailableDecision(onUnavailable, options.input, err as DeliverdError);
356
+ }
328
357
 
329
358
  /*
330
359
  * No wait when the caller said not to, and none when there is nothing to