@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/README.md CHANGED
@@ -682,6 +682,27 @@ An **agent key cannot write here**. A schedule is an instruction *to* an
682
682
  agent, so setting one is a person's decision — use a user key. Reading is
683
683
  open to both, and an agent sees only the schedules addressed to it.
684
684
 
685
+ ## Events
686
+
687
+ Be told instead of asking. Deliverd speaks MCP Events (SEP-3415): an MCP
688
+ client hears them on `/api/mcp/v2`, and this SDK reads the same log over REST.
689
+
690
+ ```ts
691
+ const approval = await deliverd.approvals.create({ title: "Refund £1,240", approvers: ["finance@firm.example"] });
692
+ const decided = await deliverd.events.waitForDecision({ approvalId: approval.id });
693
+ if (decided.status === "approved") await refund();
694
+
695
+ // Every refusal, as it happens; persist the cursor to resume after a restart.
696
+ for await (const event of deliverd.events.watch("gate.denied", {}, { onCursor: save })) page(event.data);
697
+ ```
698
+
699
+ `deliverd.events.list()` names what your key can hear: `approval.decided`,
700
+ `approval.question`, `gate.decided`, `gate.denied`, `review.settled`,
701
+ `collection.completed`, `task.updated`, `screen.held`, `drift.detected`,
702
+ `risk_indicator.breached` and `context.changed`. Events are kept seven days.
703
+ `waitForDecision` falls back to reading the request on a server without
704
+ events, and `approval.wait()` is unchanged.
705
+
685
706
  ## Webhooks
686
707
 
687
708
  Rather than polling, take the decision as it happens. Verify first — a
@@ -1 +1 @@
1
- {"version":3,"file":"data-screen.d.ts","sourceRoot":"","sources":["../src/data-screen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,+DAAgE,CAAC;AACpG,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,eAAO,MAAM,iBAAiB,yEAA0E,CAAC;AACzG,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,eAAO,MAAM,eAAe,6CAA8C,CAAC;AAC3E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAerD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAqBrB,6FAA6F;;;;;;;;;;;;;;;;;;;;;;;;;CAKlD,CAAC;AAE9C,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAC/C,eAAO,MAAM,cAAc,EAA8B,QAAQ,EAAE,CAAC;AAapE;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,cAAc,GAAG,YAAY,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,EAAE,oBAAoB,CAAC;IACrC,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AA8R7D,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;AAExG;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,UAAU,EAAO,EAAE,KAAK,GAAE,SAAS,YAAY,EAAO,GAAG,aAAa,EAAE,CA+ChI;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,YAAY,CAI1E;AAID,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAOD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,CAuBlF;AAED,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAK5F;AAID,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,sBAAsB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACpD,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,uFAAuF;IACvF,OAAO,EAAE,YAAY,CAAC;IACtB,sEAAsE;IACtE,cAAc,EAAE,YAAY,CAAC;IAC7B,qGAAqG;IACrG,aAAa,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,YAAY,EAAE;QAAE,sBAAsB,EAAE,oBAAoB,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC;CACvF;AAED,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,aAAa,CAAC;IACvB,qEAAqE;IACrE,cAAc,EAAE,oBAAoB,CAAC;IACrC,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,+FAA+F;IAC/F,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAe3D;AAOD,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAkB3D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,MAAM,GAAE,YAAoC,EAC5C,kBAAkB,GAAE,oBAAqC,GACxD,gBAAgB,CAiDlB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,aAAa,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,WAAW,CAAC,GAAG,SAAS,GAAG,IAAI,CAIzJ;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,oBAAoB,CAE7F"}
1
+ {"version":3,"file":"data-screen.d.ts","sourceRoot":"","sources":["../src/data-screen.ts"],"names":[],"mappings":"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"}
@@ -218,6 +218,15 @@ function passportValid(raw) {
218
218
  function vatValid(raw) {
219
219
  return raw === raw.toUpperCase() && digitsOf(raw).length >= 6;
220
220
  }
221
+ /**
222
+ * A password written out in a sentence or a form, "my banking password is
223
+ * Tr0ub4dor&3" or "password: Tr0ub4dor&3". It must hold a digit or a symbol,
224
+ * so "the password is required" is not one, and a mask, a placeholder or a
225
+ * variable such as ${DB_PASS} is not.
226
+ */
227
+ function spokenPasswordValid(value) {
228
+ return /[^A-Za-z]/.test(value) && !value.startsWith("$") && !/^[*•xX.]+$/.test(value) && envSecretValid(value) && !/redacted|hidden/i.test(value);
229
+ }
221
230
  /** A value in a .env line that is a placeholder, not a credential. */
222
231
  function envSecretValid(value) {
223
232
  return !/^[<{%(]/.test(value) && !/your|example|placeholder|changeme|xxxx/i.test(value);
@@ -258,6 +267,13 @@ const DETECTORS = [
258
267
  valid: envSecretValid,
259
268
  group: 1,
260
269
  },
270
+ // A password written out in words, the way people tell a person, or an assistant, their login.
271
+ {
272
+ kind: "secret",
273
+ pattern: /\b(?:pass(?:word|code|phrase)|passwd)s?(?:[ \t]+(?:is|was)(?:[ \t]*[:=])?|[ \t]*[:=])[ \t]*["']?([!#-&(-~]{5,127}[A-Za-z0-9#$%&*+\-\/<=>@^_`{|}~(\[])/gi,
274
+ valid: spokenPasswordValid,
275
+ group: 1,
276
+ },
261
277
  { kind: "iban", pattern: /\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{4}){2,7}(?: ?[A-Z0-9]{1,4})?\b/g, valid: ibanValid },
262
278
  {
263
279
  kind: "payment_card",
@@ -0,0 +1,114 @@
1
+ import type { HttpClient } from "./http.js";
2
+ /**
3
+ * Be told, instead of asking.
4
+ *
5
+ * Deliverd speaks MCP Events (io.modelcontextprotocol/events, SEP-3415): an
6
+ * approval decided, a gate settled, a review landed, a screening held for a
7
+ * person, an agent drifting. MCP clients reach them on /api/mcp/v2; this
8
+ * module reaches the same log over REST, for code that is not an MCP client.
9
+ *
10
+ * ```ts
11
+ * const approval = await deliverd.approvals.create({ title: "Refund £1,240", approvers: ["finance"] });
12
+ * const decided = await deliverd.events.waitForDecision({ approvalId: approval.id });
13
+ * if (decided.status === "approved") await refund();
14
+ * ```
15
+ *
16
+ * Nothing here changes `approval.wait()` or `gate.wait()`: they poll the
17
+ * request as they always have. This is the opt-in alternative that reads one
18
+ * cursor instead, and it falls back to reading the request itself when the
19
+ * server it is pointed at has no events (an older self-hosted copy).
20
+ */
21
+ export type EventName = "approval.decided" | "approval.question" | "approval.requested" | "gate.decided" | "gate.denied" | "review.settled" | "collection.completed" | "task.updated" | "screen.held" | "drift.detected" | "risk_indicator.breached" | "context.changed";
22
+ export interface EventArguments {
23
+ /** Only this approval, gate, review, collection, task or agent (whichever the event is about). */
24
+ id?: string;
25
+ externalId?: string;
26
+ agentId?: string;
27
+ }
28
+ export interface EventDefinition {
29
+ name: EventName | string;
30
+ title: string;
31
+ description: string;
32
+ delivery: ("poll" | "push" | "webhook")[];
33
+ inputSchema: Record<string, unknown>;
34
+ payloadSchema: Record<string, unknown>;
35
+ }
36
+ export interface EventOccurrence<D = Record<string, unknown>> {
37
+ eventId: string;
38
+ name: string;
39
+ timestamp: string;
40
+ data: D;
41
+ cursor: string | null;
42
+ }
43
+ export interface PollResult<D = Record<string, unknown>> {
44
+ events: EventOccurrence<D>[];
45
+ /** Send this back next time. */
46
+ cursor: string;
47
+ /** Events may have been missed: the cursor was older than the seven days kept. */
48
+ truncated: boolean;
49
+ /** Poll again at once. */
50
+ hasMore: boolean;
51
+ /** How long to wait before the next poll. */
52
+ nextPollMs: number;
53
+ }
54
+ export interface PollInput {
55
+ name: EventName | string;
56
+ arguments?: EventArguments;
57
+ /** `null` (or omitted) starts from now. */
58
+ cursor?: string | null;
59
+ maxAgeMs?: number;
60
+ maxEvents?: number;
61
+ }
62
+ export interface WatchOptions {
63
+ /** Start here instead of now, to resume where a previous run stopped. */
64
+ cursor?: string | null;
65
+ signal?: AbortSignal;
66
+ /** Called with each cursor as it advances, to persist it. */
67
+ onCursor?: (cursor: string) => void;
68
+ /** Never poll faster than this. Default 1000 ms, as SEP-3415 asks. */
69
+ minPollMs?: number;
70
+ }
71
+ export interface Decided {
72
+ /** approved, rejected, changes_requested, expired (and for a gate: cancelled, revoked). */
73
+ status: string;
74
+ /** For a gate: whether the action may now be performed. */
75
+ canExecute?: boolean;
76
+ /** The event's payload, or the request as read back when the server had no events. */
77
+ data: Record<string, unknown>;
78
+ /** "event" when an MCP Event told us; "read" when we fell back to reading the request. */
79
+ via: "event" | "read";
80
+ }
81
+ export declare class Events {
82
+ private readonly http;
83
+ constructor(http: HttpClient);
84
+ /** The events this key's scopes can hear. */
85
+ list(signal?: AbortSignal): Promise<EventDefinition[]>;
86
+ /** One poll: what happened since `cursor`. */
87
+ poll<D = Record<string, unknown>>(input: PollInput, signal?: AbortSignal): Promise<PollResult<D>>;
88
+ /**
89
+ * Every matching event, as it happens, until the signal aborts.
90
+ *
91
+ * ```ts
92
+ * for await (const event of deliverd.events.watch("gate.denied")) page(event.data);
93
+ * ```
94
+ */
95
+ watch<D = Record<string, unknown>>(name: EventName | string, args?: EventArguments, options?: WatchOptions): AsyncGenerator<EventOccurrence<D>>;
96
+ /**
97
+ * Wait for one approval or gate to settle, told by an event.
98
+ *
99
+ * Starts the cursor before reading the request once, so a decision that
100
+ * lands in between is caught either way. Falls back to polling the request
101
+ * when the server has no events endpoint (404), so it works against any
102
+ * Deliverd.
103
+ */
104
+ waitForDecision(target: {
105
+ approvalId: string;
106
+ } | {
107
+ gateId: string;
108
+ }, options?: {
109
+ timeout?: number;
110
+ signal?: AbortSignal;
111
+ minPollMs?: number;
112
+ }): Promise<Decided>;
113
+ }
114
+ //# sourceMappingURL=events.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}
package/dist/events.js ADDED
@@ -0,0 +1,120 @@
1
+ import { DeliverdError, DeliverdTimeoutError } from "./errors.js";
2
+ const SETTLED = new Set(["approved", "rejected", "changes_requested", "expired", "cancelled", "revoked", "denied", "allowed", "used"]);
3
+ const pause = (ms, signal) => new Promise((resolve, reject) => {
4
+ if (signal?.aborted)
5
+ return reject(new DeliverdError(0, "aborted", "The wait was aborted."));
6
+ const timer = setTimeout(resolve, ms);
7
+ signal?.addEventListener("abort", () => {
8
+ clearTimeout(timer);
9
+ reject(new DeliverdError(0, "aborted", "The wait was aborted."));
10
+ }, { once: true });
11
+ });
12
+ export class Events {
13
+ http;
14
+ constructor(http) {
15
+ this.http = http;
16
+ }
17
+ /** The events this key's scopes can hear. */
18
+ async list(signal) {
19
+ const res = await this.http.request({ method: "GET", path: "/events", signal });
20
+ return res.events;
21
+ }
22
+ /** One poll: what happened since `cursor`. */
23
+ async poll(input, signal) {
24
+ return this.http.request({
25
+ method: "POST",
26
+ path: "/events/poll",
27
+ body: { ...input, cursor: input.cursor ?? null },
28
+ signal,
29
+ });
30
+ }
31
+ /**
32
+ * Every matching event, as it happens, until the signal aborts.
33
+ *
34
+ * ```ts
35
+ * for await (const event of deliverd.events.watch("gate.denied")) page(event.data);
36
+ * ```
37
+ */
38
+ async *watch(name, args = {}, options = {}) {
39
+ let cursor = options.cursor ?? null;
40
+ const floor = Math.max(0, options.minPollMs ?? 1000);
41
+ for (;;) {
42
+ const page = await this.poll({ name, arguments: args, cursor }, options.signal);
43
+ cursor = page.cursor;
44
+ options.onCursor?.(cursor);
45
+ for (const event of page.events)
46
+ yield event;
47
+ if (!page.hasMore)
48
+ await pause(Math.max(floor, page.nextPollMs), options.signal);
49
+ }
50
+ }
51
+ /**
52
+ * Wait for one approval or gate to settle, told by an event.
53
+ *
54
+ * Starts the cursor before reading the request once, so a decision that
55
+ * lands in between is caught either way. Falls back to polling the request
56
+ * when the server has no events endpoint (404), so it works against any
57
+ * Deliverd.
58
+ */
59
+ async waitForDecision(target, options = {}) {
60
+ const isGate = "gateId" in target;
61
+ const id = isGate ? target.gateId : target.approvalId;
62
+ const name = isGate ? "gate.decided" : "approval.decided";
63
+ const readPath = isGate ? `/gates/${encodeURIComponent(id)}` : `/approvals/${encodeURIComponent(id)}`;
64
+ const deadline = options.timeout !== undefined ? Date.now() + options.timeout : Infinity;
65
+ const floor = Math.max(0, options.minPollMs ?? 1000);
66
+ const read = async () => {
67
+ const data = await this.http.request({ method: "GET", path: readPath, signal: options.signal });
68
+ const status = String(data.status ?? "");
69
+ if (!SETTLED.has(status) && !(isGate && data.canExecute === true))
70
+ return null;
71
+ return { status, ...(isGate ? { canExecute: data.canExecute === true } : {}), data, via: "read" };
72
+ };
73
+ let cursor = null;
74
+ let events = true;
75
+ try {
76
+ cursor = (await this.poll({ name, arguments: { id }, cursor: null }, options.signal)).cursor;
77
+ }
78
+ catch (err) {
79
+ if (!(err instanceof DeliverdError) || err.status !== 404)
80
+ throw err;
81
+ events = false;
82
+ }
83
+ // Already settled before we started listening.
84
+ const first = await read();
85
+ if (first)
86
+ return first;
87
+ let pollMs = 2000;
88
+ for (;;) {
89
+ if (Date.now() >= deadline)
90
+ throw new DeliverdTimeoutError(`No decision on ${id} within the timeout.`);
91
+ if (events) {
92
+ const page = await this.poll({ name, arguments: { id }, cursor }, options.signal);
93
+ cursor = page.cursor;
94
+ const hit = page.events[0];
95
+ if (hit) {
96
+ const data = hit.data;
97
+ return {
98
+ status: String(data.status),
99
+ ...(isGate ? { canExecute: data.canExecute === true } : {}),
100
+ data,
101
+ via: "event",
102
+ };
103
+ }
104
+ if (page.truncated) {
105
+ const settled = await read();
106
+ if (settled)
107
+ return settled;
108
+ }
109
+ pollMs = page.hasMore ? 0 : page.nextPollMs;
110
+ }
111
+ else {
112
+ const settled = await read();
113
+ if (settled)
114
+ return settled;
115
+ pollMs = Math.min(15_000, Math.round(pollMs * 1.5));
116
+ }
117
+ await pause(Math.max(floor, Math.min(pollMs, deadline - Date.now())), options.signal);
118
+ }
119
+ }
120
+ }
package/dist/gates.d.ts CHANGED
@@ -1,5 +1,6 @@
1
+ import { DeliverdError } from "./errors.js";
1
2
  import type { HttpClient } from "./http.js";
2
- import type { CreateGateInput, ExecutionReceipt, GateAgentRef, GateData, GateDecision, RecordExecutionInput } from "./types.js";
3
+ import type { CreateGateInput, ExecutionReceipt, GateAgentRef, GateData, GateDecision, GateOnUnavailable, RecordExecutionInput } from "./types.js";
3
4
  export interface GateWaitOptions {
4
5
  /** Give up after this many milliseconds. Without one, waits indefinitely. */
5
6
  timeout?: number;
@@ -16,6 +17,14 @@ export interface GateOptions extends GateWaitOptions {
16
17
  environment?: string;
17
18
  reason?: string;
18
19
  flowId?: string;
20
+ model?: string;
21
+ traceparent?: string;
22
+ /**
23
+ * What to do when Deliverd cannot be reached: `throw` (default), `deny` or
24
+ * `allow`. Choose per action: `deny` for a payment, `allow` for a low-risk
25
+ * read you would rather not stall. Only network failures and 5xx count.
26
+ */
27
+ onUnavailable?: GateOnUnavailable;
19
28
  /**
20
29
  * Whether to block when policy sends it to a person. Default true.
21
30
  *
@@ -141,4 +150,12 @@ export declare class Gates {
141
150
  /** One decision by its id. */
142
151
  get(id: string, signal?: AbortSignal): Promise<Gate>;
143
152
  }
153
+ /**
154
+ * Whether an error means Deliverd could not be reached, as opposed to an
155
+ * answer: a network failure or a 5xx. An abort, a timed-out wait and every 4xx
156
+ * are not, so `onUnavailable` never hides a bug or a refusal.
157
+ */
158
+ export declare function isUnavailable(err: unknown, signal?: AbortSignal): boolean;
159
+ /** The decision `onUnavailable` gives when Deliverd could not be reached. */
160
+ export declare function unavailableDecision(mode: Exclude<GateOnUnavailable, "throw">, input: Record<string, unknown>, err: DeliverdError): GateDecision;
144
161
  //# sourceMappingURL=gates.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"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"}
package/dist/gates.js CHANGED
@@ -297,3 +297,32 @@ export class Gates {
297
297
  return new Gate(this.http, data);
298
298
  }
299
299
  }
300
+ /**
301
+ * Whether an error means Deliverd could not be reached, as opposed to an
302
+ * answer: a network failure or a 5xx. An abort, a timed-out wait and every 4xx
303
+ * are not, so `onUnavailable` never hides a bug or a refusal.
304
+ */
305
+ export function isUnavailable(err, signal) {
306
+ if (!(err instanceof DeliverdError) || err instanceof DeliverdTimeoutError)
307
+ return false;
308
+ if (signal?.aborted || err.code === "aborted" || err.code === "no_api_key")
309
+ return false;
310
+ return err.status === 0 || err.status >= 500;
311
+ }
312
+ /** The decision `onUnavailable` gives when Deliverd could not be reached. */
313
+ export function unavailableDecision(mode, input, err) {
314
+ const allowed = mode === "allow";
315
+ return {
316
+ allowed,
317
+ status: allowed ? "allowed" : "denied",
318
+ reason: `Deliverd could not be reached (${err.code}), so onUnavailable: "${mode}" answered.`,
319
+ rule: null,
320
+ input,
321
+ changes: [],
322
+ id: "",
323
+ approvalUrl: null,
324
+ decisionToken: null,
325
+ gate: null,
326
+ unavailable: true,
327
+ };
328
+ }
package/dist/index.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { HttpClient, type ClientOptions } from "./http.js";
2
2
  import { Approvals, DecisionSessions, type WaitOptions } from "./approvals.js";
3
3
  import { Gates, 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";
@@ -17,6 +18,7 @@ import { type Duration } from "./duration.js";
17
18
  import type { CollectedAnswers, CreateApprovalInput, CreateCollectionInput, CreateReviewInput, Decision, GateDecision, PublishReportInput, PublishResult, ReviewOutcome } from "./types.js";
18
19
  export { Approval, Approvals, DecisionSessions, POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
19
20
  export { Gate, Gates, type GateOptions, type GateWaitOptions } from "./gates.js";
21
+ export { Events, type Decided, type EventArguments, type EventDefinition, type EventName, type EventOccurrence, type PollInput, type PollResult, type WatchOptions, } from "./events.js";
20
22
  export { Comments, Reports, Schedules } from "./reports.js";
21
23
  export { Review, Reviews, type ReviewWaitOptions } from "./reviews.js";
22
24
  export { Collection, Collections, type CollectWaitOptions } from "./collections.js";
@@ -144,6 +146,8 @@ export declare class Deliverd {
144
146
  readonly webhookEndpoints: WebhookEndpoints;
145
147
  /** Check a gate's signed yes where the action happens, before it happens. */
146
148
  readonly decisionTokens: DecisionTokens;
149
+ /** Be told instead of asking: MCP Events (approval.decided, gate.decided...) over REST. */
150
+ readonly events: Events;
147
151
  readonly http: HttpClient;
148
152
  /** Whether an imaginary approver is deciding these. */
149
153
  readonly development: boolean;
@@ -191,6 +195,12 @@ export declare class Deliverd {
191
195
  *
192
196
  * `wait: false` returns a pending decision immediately; `deliverd.gates`
193
197
  * is the same thing with the handle exposed.
198
+ *
199
+ * `onUnavailable` decides what happens when Deliverd cannot be reached (a
200
+ * network failure or a 5xx, never a 4xx): `throw` by default, or `deny` or
201
+ * `allow` per action. It applies to the first check only, never to a wait
202
+ * for a person. Such a decision has `unavailable: true`, an empty id
203
+ * and no decision token, and nothing is recorded in Deliverd.
194
204
  */
195
205
  gate(options: GateOptions): Promise<GateDecision>;
196
206
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/dist/index.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { HttpClient } from "./http.js";
2
2
  import { Approvals, DecisionSessions, FAST_POLL_SCHEDULE } from "./approvals.js";
3
- import { Gates } from "./gates.js";
3
+ import { Gates, isUnavailable, unavailableDecision } from "./gates.js";
4
+ import { Events } from "./events.js";
4
5
  import { Comments, Reports, Schedules } from "./reports.js";
5
6
  import { Reviews } from "./reviews.js";
6
7
  import { Collections } from "./collections.js";
@@ -16,6 +17,7 @@ import { developmentFetch } from "./dev.js";
16
17
  import { durationMs } from "./duration.js";
17
18
  export { Approval, Approvals, DecisionSessions, POLL_SCHEDULE } from "./approvals.js";
18
19
  export { Gate, Gates } from "./gates.js";
20
+ export { Events, } from "./events.js";
19
21
  export { Comments, Reports, Schedules } from "./reports.js";
20
22
  export { Review, Reviews } from "./reviews.js";
21
23
  export { Collection, Collections } from "./collections.js";
@@ -75,6 +77,8 @@ export class Deliverd {
75
77
  webhookEndpoints;
76
78
  /** Check a gate's signed yes where the action happens, before it happens. */
77
79
  decisionTokens;
80
+ /** Be told instead of asking: MCP Events (approval.decided, gate.decided...) over REST. */
81
+ events;
78
82
  http;
79
83
  /** Whether an imaginary approver is deciding these. */
80
84
  development;
@@ -109,6 +113,7 @@ export class Deliverd {
109
113
  this.webhooks = new Webhooks();
110
114
  this.webhookEndpoints = new WebhookEndpoints(this.http);
111
115
  this.decisionTokens = new DecisionTokens(this.http.baseUrl, options.fetch);
116
+ this.events = new Events(this.http);
112
117
  }
113
118
  /**
114
119
  * Ask a person, and wait for the answer.
@@ -188,10 +193,26 @@ export class Deliverd {
188
193
  *
189
194
  * `wait: false` returns a pending decision immediately; `deliverd.gates`
190
195
  * is the same thing with the handle exposed.
196
+ *
197
+ * `onUnavailable` decides what happens when Deliverd cannot be reached (a
198
+ * network failure or a 5xx, never a 4xx): `throw` by default, or `deny` or
199
+ * `allow` per action. It applies to the first check only, never to a wait
200
+ * for a person. Such a decision has `unavailable: true`, an empty id
201
+ * and no decision token, and nothing is recorded in Deliverd.
191
202
  */
192
203
  async gate(options) {
193
- const { action, timeout, onPoll, signal, wait, pollIntervals, ...rest } = options;
194
- const gate = await this.gates.create({ actionId: action, ...rest }, signal);
204
+ const { action, timeout, onPoll, signal, wait, pollIntervals, onUnavailable = "throw", ...rest } = options;
205
+ let gate;
206
+ try {
207
+ gate = await this.gates.create({ actionId: action, ...rest }, signal);
208
+ }
209
+ catch (err) {
210
+ /* Only the first check. Once a person is deciding, an outage during the
211
+ * wait is never turned into a yes or a no on their behalf. */
212
+ if (onUnavailable === "throw" || !isUnavailable(err, signal))
213
+ throw err;
214
+ return unavailableDecision(onUnavailable, options.input, err);
215
+ }
195
216
  /*
196
217
  * No wait when the caller said not to, and none when there is nothing to
197
218
  * wait for — a rule that allowed or denied it has already answered, which
@@ -43,7 +43,7 @@
43
43
  * **Add the version here when you publish it, not before.** An entry is a
44
44
  * claim that `npm install @deliverd/sdk@x` works today.
45
45
  */
46
- export declare const PUBLISHED_TO_NPM: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.6.2", "0.7.0", "0.7.1", "0.8.0", "0.8.1", "0.8.2", "0.9.0", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.13.0", "0.14.0", "0.15.0", "0.16.0", "0.17.0", "0.18.0", "0.19.0", "0.20.0", "0.21.0", "0.22.0", "0.23.0", "0.24.0", "0.24.1", "0.25.0", "0.25.1", "0.26.0", "0.27.0", "0.28.0", "0.29.0", "0.30.0", "0.31.0", "0.32.0", "0.33.0", "0.34.0", "0.35.0", "0.36.0", "0.37.0", "0.38.0", "0.39.0", "0.39.1"];
46
+ export declare const PUBLISHED_TO_NPM: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.6.2", "0.7.0", "0.7.1", "0.8.0", "0.8.1", "0.8.2", "0.9.0", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.13.0", "0.14.0", "0.15.0", "0.16.0", "0.17.0", "0.18.0", "0.19.0", "0.20.0", "0.21.0", "0.22.0", "0.23.0", "0.24.0", "0.24.1", "0.25.0", "0.25.1", "0.26.0", "0.27.0", "0.28.0", "0.29.0", "0.30.0", "0.31.0", "0.32.0", "0.33.0", "0.34.0", "0.35.0", "0.36.0", "0.37.0", "0.38.0", "0.39.0", "0.39.1", "0.40.0", "0.41.0"];
47
47
  /**
48
48
  * A fingerprint of what each *published* version recorded.
49
49
  *
@@ -1 +1 @@
1
- {"version":3,"file":"released.d.ts","sourceRoot":"","sources":["../src/released.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,6dAiDnB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA+HzC,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CA0/yCtD,CAAC"}
1
+ {"version":3,"file":"released.d.ts","sourceRoot":"","sources":["../src/released.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,ifAmDnB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAmIzC,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAuj5CtD,CAAC"}