@deliverd/sdk 0.10.0 → 0.11.1
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/LICENSE +21 -21
- package/README.md +654 -654
- package/dist/dev.d.ts.map +1 -1
- package/dist/dev.js +82 -0
- package/dist/gates.d.ts +49 -1
- package/dist/gates.d.ts.map +1 -1
- package/dist/gates.js +110 -3
- package/dist/messages.d.ts.map +1 -1
- package/dist/messages.js +48 -0
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +1067 -0
- package/dist/types.d.ts +162 -9
- package/dist/types.d.ts.map +1 -1
- package/package.json +59 -59
- package/src/adapters/ai-sdk.ts +59 -59
- package/src/adapters/claude-agent-sdk.ts +90 -90
- package/src/adapters/index.ts +23 -23
- package/src/adapters/langgraph.ts +202 -202
- package/src/adapters/openai-agents.ts +112 -112
- package/src/adapters/shared.ts +179 -179
- package/src/approvals.ts +342 -342
- package/src/collections.ts +247 -247
- package/src/dev.ts +868 -782
- package/src/duration.ts +21 -21
- package/src/errors.ts +62 -62
- package/src/flows.ts +222 -222
- package/src/gates.ts +366 -231
- package/src/http.ts +217 -217
- package/src/index.ts +444 -444
- package/src/messages.ts +209 -161
- package/src/paging.ts +64 -64
- package/src/released.ts +4049 -2982
- package/src/reports.ts +490 -490
- package/src/reviews.ts +236 -236
- package/src/types.ts +1107 -933
- package/src/webhooks.ts +117 -117
package/dist/dev.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAMb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAE7F,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,GAAG,CAAC,CAAC,OAAO,EAAE,YAAY,KAAK,kBAAkB,CAAC,CAAC;IAC/E,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAcD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,UAAU,CAAC,KAAK,
|
|
1
|
+
{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAMb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAE7F,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,GAAG,CAAC,CAAC,OAAO,EAAE,YAAY,KAAK,kBAAkB,CAAC,CAAC;IAC/E,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAcD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,UAAU,CAAC,KAAK,CAgjB1F"}
|
package/dist/dev.js
CHANGED
|
@@ -215,6 +215,39 @@ export function developmentFetch(options = {}) {
|
|
|
215
215
|
outcome: null,
|
|
216
216
|
settledAt: null,
|
|
217
217
|
reused: false,
|
|
218
|
+
decision: byRule ? "DENY" : "APPROVAL_REQUIRED",
|
|
219
|
+
canExecute: false,
|
|
220
|
+
blockedBecause: byRule ? "Policy does not allow this action." : "Waiting for a person to decide.",
|
|
221
|
+
scope: {
|
|
222
|
+
destination: body.destination ?? null,
|
|
223
|
+
// Offline there is no directory to consult, so nothing is known to be internal.
|
|
224
|
+
recipientScope: body.destination ? "external" : null,
|
|
225
|
+
classification: body.classification ?? null,
|
|
226
|
+
risk: body.risk ?? null,
|
|
227
|
+
artifact: body.artifact
|
|
228
|
+
? {
|
|
229
|
+
kind: body.artifact.versionId ? "report_version" : "external",
|
|
230
|
+
reportId: body.artifact.reportId ?? null,
|
|
231
|
+
versionId: body.artifact.versionId ?? null,
|
|
232
|
+
versionNumber: null,
|
|
233
|
+
sha256: (body.artifact.sha256 ?? null)?.toLowerCase() ?? null,
|
|
234
|
+
name: body.artifact.name ?? null,
|
|
235
|
+
mimeType: null,
|
|
236
|
+
size: null,
|
|
237
|
+
uri: null,
|
|
238
|
+
verified: false,
|
|
239
|
+
}
|
|
240
|
+
: null,
|
|
241
|
+
digest: null,
|
|
242
|
+
},
|
|
243
|
+
authorisation: { validUntil: null, maxUses: 1, usesRemaining: 1 },
|
|
244
|
+
actionId: String(body.actionId ?? ""),
|
|
245
|
+
agentId: null,
|
|
246
|
+
flowId: body.flowId ?? null,
|
|
247
|
+
supersedesGateId: body.supersedesGateId ?? null,
|
|
248
|
+
description: (body.description ?? body.reason) ?? null,
|
|
249
|
+
requestedBy: "Development agent",
|
|
250
|
+
createdAt: new Date().toISOString(),
|
|
218
251
|
};
|
|
219
252
|
gateStore.set(id, {
|
|
220
253
|
data: { gate, externalId },
|
|
@@ -223,6 +256,53 @@ export function developmentFetch(options = {}) {
|
|
|
223
256
|
});
|
|
224
257
|
return json(gate, 201);
|
|
225
258
|
}
|
|
259
|
+
/*
|
|
260
|
+
* What was done with a permission, offline: one use, spent by the first
|
|
261
|
+
* claim, and a hash that has to match the one asked about — the two
|
|
262
|
+
* refusals worth rehearsing before there is an account to be refused by.
|
|
263
|
+
*/
|
|
264
|
+
const executionMatch = /^\/gates\/([^/]+)\/(execution|cancel)$/.exec(path);
|
|
265
|
+
if (executionMatch && method === "POST") {
|
|
266
|
+
const stored = gateStore.get(executionMatch[1]);
|
|
267
|
+
if (!stored) {
|
|
268
|
+
return json({ error: { code: "not_found", message: "No such gate in this development session." } }, 404);
|
|
269
|
+
}
|
|
270
|
+
settleGate(stored);
|
|
271
|
+
const gate = stored.data.gate;
|
|
272
|
+
if (executionMatch[2] === "cancel") {
|
|
273
|
+
gate.status = "cancelled";
|
|
274
|
+
gate.canExecute = false;
|
|
275
|
+
gate.blockedBecause = "This request was withdrawn.";
|
|
276
|
+
return json(gate);
|
|
277
|
+
}
|
|
278
|
+
if (!gate.canExecute) {
|
|
279
|
+
const code = gate.status === "used" ? "gate_used" : "not_authorised";
|
|
280
|
+
return json({ error: { code, message: gate.blockedBecause ?? "Not authorised." } }, code === "gate_used" ? 409 : 403);
|
|
281
|
+
}
|
|
282
|
+
const sha = typeof body.artifactSha256 === "string" ? body.artifactSha256.toLowerCase() : null;
|
|
283
|
+
if (gate.scope.artifact?.sha256 && sha !== gate.scope.artifact.sha256) {
|
|
284
|
+
return json({ error: { code: sha ? "approval_invalidated" : "artifact_missing", message: "The artifact is not the one that was approved." } }, sha ? 409 : 400);
|
|
285
|
+
}
|
|
286
|
+
gate.status = "used";
|
|
287
|
+
gate.canExecute = false;
|
|
288
|
+
gate.blockedBecause = "This permission has been used. A further action needs a new request.";
|
|
289
|
+
gate.authorisation = { ...gate.authorisation, usesRemaining: 0 };
|
|
290
|
+
const receipt = {
|
|
291
|
+
id: `exe_dev_${++counter}`,
|
|
292
|
+
gateId: gate.id,
|
|
293
|
+
phase: body.phase ?? "completed",
|
|
294
|
+
claimId: null,
|
|
295
|
+
executedAt: new Date().toISOString(),
|
|
296
|
+
artifactSha256: sha,
|
|
297
|
+
destination: body.destination ?? null,
|
|
298
|
+
result: body.result ?? {},
|
|
299
|
+
verification: gate.scope.artifact?.sha256 ? "hash_matched" : "reported",
|
|
300
|
+
detail: body.detail ?? null,
|
|
301
|
+
reportedBy: "Development agent",
|
|
302
|
+
createdAt: new Date().toISOString(),
|
|
303
|
+
};
|
|
304
|
+
return json({ receipt, gate }, 201);
|
|
305
|
+
}
|
|
226
306
|
const gateMatch = /^\/gates\/([^/]+)$/.exec(path);
|
|
227
307
|
if (gateMatch && method === "GET") {
|
|
228
308
|
const stored = gateStore.get(gateMatch[1]);
|
|
@@ -527,6 +607,8 @@ function settleGate(stored) {
|
|
|
527
607
|
const approved = stored.outcome === "approved";
|
|
528
608
|
gate.status = approved ? "approved" : "rejected";
|
|
529
609
|
gate.allowed = approved;
|
|
610
|
+
gate.canExecute = approved;
|
|
611
|
+
gate.blockedBecause = approved ? null : "A person rejected this action.";
|
|
530
612
|
gate.outcome = approved ? "approved" : "rejected";
|
|
531
613
|
gate.settledAt = new Date().toISOString();
|
|
532
614
|
gate.basis = "human";
|
package/dist/gates.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { HttpClient } from "./http.js";
|
|
2
|
-
import type { CreateGateInput, GateData, GateDecision } from "./types.js";
|
|
2
|
+
import type { CreateGateInput, ExecutionReceipt, GateAgentRef, GateData, GateDecision, RecordExecutionInput } from "./types.js";
|
|
3
3
|
export interface GateWaitOptions {
|
|
4
4
|
/** Give up after this many milliseconds. Without one, waits indefinitely. */
|
|
5
5
|
timeout?: number;
|
|
@@ -59,6 +59,30 @@ export declare class Gate {
|
|
|
59
59
|
get approvalId(): string | null;
|
|
60
60
|
/** True when this call read back a decision already made under your id. */
|
|
61
61
|
get reused(): boolean;
|
|
62
|
+
/**
|
|
63
|
+
* Whether you may act on it **now**: authorised, inside its window, with a
|
|
64
|
+
* use left, not revoked. Branch on this rather than `allowed`, which says it
|
|
65
|
+
* was authorised at some point. The organisation's authorisation only.
|
|
66
|
+
*/
|
|
67
|
+
get canExecute(): boolean;
|
|
68
|
+
/** What policy said: ALLOW, APPROVAL_REQUIRED, REVIEW_REQUIRED or DENY. */
|
|
69
|
+
get decision(): GateData["decision"];
|
|
70
|
+
/** Why it cannot be executed, when it cannot. */
|
|
71
|
+
get blockedBecause(): string | null;
|
|
72
|
+
/** What the permission covers: destination, artifact and its hash, classification. */
|
|
73
|
+
get scope(): GateData["scope"];
|
|
74
|
+
/** How long it lasts and how many uses are left. */
|
|
75
|
+
get authorisation(): GateData["authorisation"];
|
|
76
|
+
/** A person sent it back. Revise and ask again with `supersedesGateId: gate.id`. */
|
|
77
|
+
get changesRequested(): boolean;
|
|
78
|
+
/**
|
|
79
|
+
* Report what you did with the permission. Spends a use. A different
|
|
80
|
+
* artifact hash is refused as `approval_invalidated`; a different
|
|
81
|
+
* destination as `destination_mismatch`.
|
|
82
|
+
*/
|
|
83
|
+
recordExecution(input?: RecordExecutionInput, signal?: AbortSignal): Promise<ExecutionReceipt>;
|
|
84
|
+
/** Withdraw it: the request if a person has not answered, the permission if unused. */
|
|
85
|
+
cancel(note?: string, agent?: GateAgentRef, signal?: AbortSignal): Promise<this>;
|
|
62
86
|
/** Everything the API returned, if you want a field the getters do not name. */
|
|
63
87
|
toJSON(): GateData;
|
|
64
88
|
/** The answer, flattened — what `gate()` hands back. */
|
|
@@ -81,6 +105,30 @@ export declare class Gate {
|
|
|
81
105
|
export declare class Gates {
|
|
82
106
|
private readonly http;
|
|
83
107
|
constructor(http: HttpClient);
|
|
108
|
+
/**
|
|
109
|
+
* Ask whether you may act, and return at once — the same call as `create`,
|
|
110
|
+
* named for what it does. Policy answers; `canExecute` is the field to branch
|
|
111
|
+
* on, now or after `wait()`.
|
|
112
|
+
*/
|
|
113
|
+
check(input: CreateGateInput, signal?: AbortSignal): Promise<Gate>;
|
|
114
|
+
/** Report what you did with a gate's permission. See `Gate.recordExecution`. */
|
|
115
|
+
recordExecution(id: string, input?: RecordExecutionInput, signal?: AbortSignal): Promise<{
|
|
116
|
+
receipt: ExecutionReceipt;
|
|
117
|
+
gate: Gate;
|
|
118
|
+
}>;
|
|
119
|
+
/** Withdraw a request, or an unused permission. */
|
|
120
|
+
cancel(id: string, note?: string, agent?: GateAgentRef, signal?: AbortSignal): Promise<Gate>;
|
|
121
|
+
/**
|
|
122
|
+
* Have Deliverd make the staged report version the gate authorised live.
|
|
123
|
+
* The receipt is `verified`: Deliverd carried it out.
|
|
124
|
+
*/
|
|
125
|
+
release(id: string, agent?: GateAgentRef, signal?: AbortSignal): Promise<{
|
|
126
|
+
receipt: ExecutionReceipt;
|
|
127
|
+
gate: Gate;
|
|
128
|
+
url: string;
|
|
129
|
+
}>;
|
|
130
|
+
/** The gate's evidence pack, as JSON. */
|
|
131
|
+
evidence(id: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
|
|
84
132
|
/**
|
|
85
133
|
* Raise a decision and return straight away, even if it went to a person.
|
|
86
134
|
*
|
package/dist/gates.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"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"}
|
package/dist/gates.js
CHANGED
|
@@ -18,10 +18,32 @@ import { DeliverdError, DeliverdTimeoutError } from "./errors.js";
|
|
|
18
18
|
* ```
|
|
19
19
|
*
|
|
20
20
|
* **Use `decision.input`, not your own object.** It is what the action's schema
|
|
21
|
-
* validated and what an approver actually saw
|
|
22
|
-
* it is what execution will be checked against. Passing the original is right
|
|
21
|
+
* validated and what an approver actually saw. Passing the original is right
|
|
23
22
|
* until the day somebody edits a value before approving, and then it is a
|
|
24
23
|
* silent bug that spends an approval for £1200 on a refund of £1240.
|
|
24
|
+
*
|
|
25
|
+
* **Scoped permissions.** Name what the act is about and where it lands, and an
|
|
26
|
+
* approval covers exactly that — the version you asked about, the destination
|
|
27
|
+
* you named — then report what you did:
|
|
28
|
+
*
|
|
29
|
+
* ```ts
|
|
30
|
+
* const gate = await deliverd.gates.check({
|
|
31
|
+
* actionId: "report.publish",
|
|
32
|
+
* externalId: `weekly-portfolio:${week}`,
|
|
33
|
+
* input: { title: "Weekly Portfolio Report" },
|
|
34
|
+
* classification: "confidential",
|
|
35
|
+
* destination: { type: "workspace", id: "executive" },
|
|
36
|
+
* artifact: { reportId, versionId },
|
|
37
|
+
* });
|
|
38
|
+
* await gate.wait();
|
|
39
|
+
* if (gate.canExecute) {
|
|
40
|
+
* await publish(report);
|
|
41
|
+
* await gate.recordExecution({ artifactSha256: gate.scope.artifact?.sha256 ?? undefined });
|
|
42
|
+
* }
|
|
43
|
+
* ```
|
|
44
|
+
*
|
|
45
|
+
* `canExecute` is your organisation's authorisation, nothing more: the platform
|
|
46
|
+
* your agent runs on may still require its user's confirmation, or refuse.
|
|
25
47
|
*/
|
|
26
48
|
/** How long between polls while waiting on a person. */
|
|
27
49
|
const POLL_SCHEDULE = [250, 750, 2_000, 4_000, 8_000, 15_000, 30_000];
|
|
@@ -62,6 +84,42 @@ export class Gate {
|
|
|
62
84
|
get approvalId() { return this.data.approvalId; }
|
|
63
85
|
/** True when this call read back a decision already made under your id. */
|
|
64
86
|
get reused() { return this.data.reused; }
|
|
87
|
+
/**
|
|
88
|
+
* Whether you may act on it **now**: authorised, inside its window, with a
|
|
89
|
+
* use left, not revoked. Branch on this rather than `allowed`, which says it
|
|
90
|
+
* was authorised at some point. The organisation's authorisation only.
|
|
91
|
+
*/
|
|
92
|
+
get canExecute() { return this.data.canExecute; }
|
|
93
|
+
/** What policy said: ALLOW, APPROVAL_REQUIRED, REVIEW_REQUIRED or DENY. */
|
|
94
|
+
get decision() { return this.data.decision; }
|
|
95
|
+
/** Why it cannot be executed, when it cannot. */
|
|
96
|
+
get blockedBecause() { return this.data.blockedBecause; }
|
|
97
|
+
/** What the permission covers: destination, artifact and its hash, classification. */
|
|
98
|
+
get scope() { return this.data.scope; }
|
|
99
|
+
/** How long it lasts and how many uses are left. */
|
|
100
|
+
get authorisation() { return this.data.authorisation; }
|
|
101
|
+
/** A person sent it back. Revise and ask again with `supersedesGateId: gate.id`. */
|
|
102
|
+
get changesRequested() { return this.data.status === "changes_requested"; }
|
|
103
|
+
/**
|
|
104
|
+
* Report what you did with the permission. Spends a use. A different
|
|
105
|
+
* artifact hash is refused as `approval_invalidated`; a different
|
|
106
|
+
* destination as `destination_mismatch`.
|
|
107
|
+
*/
|
|
108
|
+
async recordExecution(input = {}, signal) {
|
|
109
|
+
const { receipt, gate } = await recordExecution(this.http, this.data.id, input, signal);
|
|
110
|
+
this.data = gate;
|
|
111
|
+
return receipt;
|
|
112
|
+
}
|
|
113
|
+
/** Withdraw it: the request if a person has not answered, the permission if unused. */
|
|
114
|
+
async cancel(note, agent, signal) {
|
|
115
|
+
this.data = await this.http.request({
|
|
116
|
+
method: "POST",
|
|
117
|
+
path: `/gates/${this.data.id}/cancel`,
|
|
118
|
+
body: { note, agent },
|
|
119
|
+
signal,
|
|
120
|
+
});
|
|
121
|
+
return this;
|
|
122
|
+
}
|
|
65
123
|
/** Everything the API returned, if you want a field the getters do not name. */
|
|
66
124
|
toJSON() { return this.data; }
|
|
67
125
|
/** The answer, flattened — what `gate()` hands back. */
|
|
@@ -111,7 +169,8 @@ export class Gate {
|
|
|
111
169
|
}
|
|
112
170
|
if (deadline !== undefined && Date.now() >= deadline) {
|
|
113
171
|
throw new DeliverdTimeoutError(`Nobody decided the ${this.data.rule ? `"${this.data.rule}" ` : ""}gate on ` +
|
|
114
|
-
|
|
172
|
+
// The action id, not an input field that happened to be called `action`.
|
|
173
|
+
`"${this.data.actionId || this.id}" within the timeout. ` +
|
|
115
174
|
(this.data.approvalUrl
|
|
116
175
|
? `It is still open at ${this.data.approvalUrl}.`
|
|
117
176
|
: "It is still open."));
|
|
@@ -147,11 +206,59 @@ function sleep(ms, signal) {
|
|
|
147
206
|
signal?.addEventListener("abort", onAbort, { once: true });
|
|
148
207
|
});
|
|
149
208
|
}
|
|
209
|
+
async function recordExecution(http, id, input, signal) {
|
|
210
|
+
return http.request({
|
|
211
|
+
method: "POST",
|
|
212
|
+
path: `/gates/${id}/execution`,
|
|
213
|
+
body: { phase: "completed", ...input },
|
|
214
|
+
signal,
|
|
215
|
+
});
|
|
216
|
+
}
|
|
150
217
|
export class Gates {
|
|
151
218
|
http;
|
|
152
219
|
constructor(http) {
|
|
153
220
|
this.http = http;
|
|
154
221
|
}
|
|
222
|
+
/**
|
|
223
|
+
* Ask whether you may act, and return at once — the same call as `create`,
|
|
224
|
+
* named for what it does. Policy answers; `canExecute` is the field to branch
|
|
225
|
+
* on, now or after `wait()`.
|
|
226
|
+
*/
|
|
227
|
+
async check(input, signal) {
|
|
228
|
+
return this.create(input, signal);
|
|
229
|
+
}
|
|
230
|
+
/** Report what you did with a gate's permission. See `Gate.recordExecution`. */
|
|
231
|
+
async recordExecution(id, input = {}, signal) {
|
|
232
|
+
const { receipt, gate } = await recordExecution(this.http, id, input, signal);
|
|
233
|
+
return { receipt, gate: new Gate(this.http, gate) };
|
|
234
|
+
}
|
|
235
|
+
/** Withdraw a request, or an unused permission. */
|
|
236
|
+
async cancel(id, note, agent, signal) {
|
|
237
|
+
const data = await this.http.request({
|
|
238
|
+
method: "POST",
|
|
239
|
+
path: `/gates/${id}/cancel`,
|
|
240
|
+
body: { note, agent },
|
|
241
|
+
signal,
|
|
242
|
+
});
|
|
243
|
+
return new Gate(this.http, data);
|
|
244
|
+
}
|
|
245
|
+
/**
|
|
246
|
+
* Have Deliverd make the staged report version the gate authorised live.
|
|
247
|
+
* The receipt is `verified`: Deliverd carried it out.
|
|
248
|
+
*/
|
|
249
|
+
async release(id, agent, signal) {
|
|
250
|
+
const released = await this.http.request({
|
|
251
|
+
method: "POST",
|
|
252
|
+
path: `/gates/${id}/release`,
|
|
253
|
+
body: { agent },
|
|
254
|
+
signal,
|
|
255
|
+
});
|
|
256
|
+
return { ...released, gate: new Gate(this.http, released.gate) };
|
|
257
|
+
}
|
|
258
|
+
/** The gate's evidence pack, as JSON. */
|
|
259
|
+
async evidence(id, signal) {
|
|
260
|
+
return this.http.request({ method: "GET", path: `/gates/${id}/evidence`, signal });
|
|
261
|
+
}
|
|
155
262
|
/**
|
|
156
263
|
* Raise a decision and return straight away, even if it went to a person.
|
|
157
264
|
*
|
package/dist/messages.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,
|
|
1
|
+
{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAsLpD,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAI5F"}
|
package/dist/messages.js
CHANGED
|
@@ -140,6 +140,54 @@ export const EXPLANATIONS = {
|
|
|
140
140
|
superseded: {
|
|
141
141
|
hint: "It was replaced while you were working. Read the current one and act on that; copy its contents into a new version rather than reviving the old, because a past decision points at what it said.",
|
|
142
142
|
},
|
|
143
|
+
approval_invalidated: {
|
|
144
|
+
message: "The artifact is not the one that was approved.",
|
|
145
|
+
hint: "Its hash changed after the decision, so the permission does not cover it. Ask again for this version; the new request can name the old one as `supersedesGateId`.",
|
|
146
|
+
},
|
|
147
|
+
destination_mismatch: {
|
|
148
|
+
message: "That destination is not the one that was approved.",
|
|
149
|
+
hint: "A permission covers the destination it was asked for. Ask again for the new one rather than sending somewhere else under it.",
|
|
150
|
+
},
|
|
151
|
+
artifact_missing: {
|
|
152
|
+
message: "This permission is for a specific artifact, and none was named.",
|
|
153
|
+
hint: "Send the SHA-256 of what you are about to use, so it can be checked against what was approved.",
|
|
154
|
+
},
|
|
155
|
+
gate_used: {
|
|
156
|
+
message: "That permission has been used.",
|
|
157
|
+
hint: "A permission covers one use unless policy said otherwise. Ask again for the next action.",
|
|
158
|
+
},
|
|
159
|
+
gate_expired: {
|
|
160
|
+
message: "The window on that permission has closed.",
|
|
161
|
+
hint: "Ask again. The window is set by policy, and an approval does not stretch to cover the same act later.",
|
|
162
|
+
},
|
|
163
|
+
gate_revoked: {
|
|
164
|
+
message: "That permission was withdrawn after it was given.",
|
|
165
|
+
hint: "Do not act. Read the gate for who revoked it and why, and ask again if the work still needs doing.",
|
|
166
|
+
},
|
|
167
|
+
gate_cancelled: {
|
|
168
|
+
message: "That request was withdrawn.",
|
|
169
|
+
hint: "Ask again if the work still needs doing.",
|
|
170
|
+
},
|
|
171
|
+
not_authorised: {
|
|
172
|
+
message: "Nothing authorises this yet.",
|
|
173
|
+
hint: "Read `blockedBecause` on the gate: it is waiting on a person, was refused, or was sent back for changes. Act only when `canExecute` is true.",
|
|
174
|
+
},
|
|
175
|
+
idempotency_conflict: {
|
|
176
|
+
message: "That external id was already used for a different act.",
|
|
177
|
+
hint: "An external id names one decision. Use a new id for a different action, destination or artifact.",
|
|
178
|
+
},
|
|
179
|
+
claim_not_found: {
|
|
180
|
+
message: "No started execution with that claim id.",
|
|
181
|
+
hint: "Send the `claimId` the `started` receipt returned, or report `completed` without one.",
|
|
182
|
+
},
|
|
183
|
+
claim_finished: {
|
|
184
|
+
message: "That execution has already been reported finished.",
|
|
185
|
+
hint: "Each claim finishes once. Read the gate for its receipts rather than reporting again.",
|
|
186
|
+
},
|
|
187
|
+
artifact_mismatch: {
|
|
188
|
+
message: "That artifact does not belong to the report named.",
|
|
189
|
+
hint: "Name a version of the same report, or leave `versionId` out to bind the current one.",
|
|
190
|
+
},
|
|
143
191
|
invalid_signature: {
|
|
144
192
|
hint: "Check the endpoint's signing secret, and that you passed the raw request body rather than a re-encoded object.",
|
|
145
193
|
},
|
package/dist/released.d.ts
CHANGED
|
@@ -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"];
|
|
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"];
|
|
47
47
|
/**
|
|
48
48
|
* A fingerprint of what each *published* version recorded.
|
|
49
49
|
*
|
package/dist/released.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"released.d.ts","sourceRoot":"","sources":["../src/released.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,
|
|
1
|
+
{"version":3,"file":"released.d.ts","sourceRoot":"","sources":["../src/released.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,6JAiBnB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAwCzC,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAo1HtD,CAAC"}
|