@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/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,CA4d1F"}
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
  *
@@ -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,EAAE,eAAe,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA8B1E,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iDAAiD;IACjD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IAClC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,IAAI;IAEb,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,IAAI;gBADK,IAAI,EAAE,UAAU,EACzB,IAAI,EAAE,QAAQ;IAGxB,IAAI,EAAE,IAAI,MAAM,CAAyB;IACzC,IAAI,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAA6B;IAC7D;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAA8B;IACpD,iCAAiC;IACjC,IAAI,OAAO,IAAI,OAAO,CAA2C;IACjE,0DAA0D;IAC1D,IAAI,MAAM,IAAI,OAAO,CAA0C;IAC/D,2EAA2E;IAC3E,IAAI,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAA4B;IAChE,mDAAmD;IACnD,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAA6B;IACxD,oEAAoE;IACpE,IAAI,IAAI,IAAI,MAAM,GAAG,IAAI,CAA2B;IACpD,kDAAkD;IAClD,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAAkC;IAClE,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAAiC;IAChE,2EAA2E;IAC3E,IAAI,MAAM,IAAI,OAAO,CAA6B;IAElD,gFAAgF;IAChF,MAAM,IAAI,QAAQ;IAElB,wDAAwD;IACxD,UAAU,IAAI,YAAY;IAcpB,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IASlD;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;CAgCzD;AAyBD,qBAAa,KAAK;IACJ,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzE,8BAA8B;IACxB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ3D"}
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,EACV,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAoDpB,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iDAAiD;IACjD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IAClC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,IAAI;IAEb,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,IAAI;gBADK,IAAI,EAAE,UAAU,EACzB,IAAI,EAAE,QAAQ;IAGxB,IAAI,EAAE,IAAI,MAAM,CAAyB;IACzC,IAAI,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAA6B;IAC7D;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAA8B;IACpD,iCAAiC;IACjC,IAAI,OAAO,IAAI,OAAO,CAA2C;IACjE,0DAA0D;IAC1D,IAAI,MAAM,IAAI,OAAO,CAA0C;IAC/D,2EAA2E;IAC3E,IAAI,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAA4B;IAChE,mDAAmD;IACnD,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAA6B;IACxD,oEAAoE;IACpE,IAAI,IAAI,IAAI,MAAM,GAAG,IAAI,CAA2B;IACpD,kDAAkD;IAClD,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAAkC;IAClE,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAAiC;IAChE,2EAA2E;IAC3E,IAAI,MAAM,IAAI,OAAO,CAA6B;IAClD;;;;OAIG;IACH,IAAI,UAAU,IAAI,OAAO,CAAiC;IAC1D,2EAA2E;IAC3E,IAAI,QAAQ,IAAI,QAAQ,CAAC,UAAU,CAAC,CAA+B;IACnE,iDAAiD;IACjD,IAAI,cAAc,IAAI,MAAM,GAAG,IAAI,CAAqC;IACxE,sFAAsF;IACtF,IAAI,KAAK,IAAI,QAAQ,CAAC,OAAO,CAAC,CAA4B;IAC1D,oDAAoD;IACpD,IAAI,aAAa,IAAI,QAAQ,CAAC,eAAe,CAAC,CAAoC;IAClF,oFAAoF;IACpF,IAAI,gBAAgB,IAAI,OAAO,CAAqD;IAEpF;;;;OAIG;IACG,eAAe,CAAC,KAAK,GAAE,oBAAyB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAMxG,uFAAuF;IACjF,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtF,gFAAgF;IAChF,MAAM,IAAI,QAAQ;IAElB,wDAAwD;IACxD,UAAU,IAAI,YAAY;IAcpB,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IASlD;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;CAiCzD;AAuCD,qBAAa,KAAK;IACJ,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxE,gFAAgF;IAC1E,eAAe,CACnB,EAAE,EAAE,MAAM,EACV,KAAK,GAAE,oBAAyB,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,OAAO,EAAE,gBAAgB,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC;IAKrD,mDAAmD;IAC7C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlG;;;OAGG;IACG,OAAO,CACX,EAAE,EAAE,MAAM,EACV,KAAK,CAAC,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,OAAO,EAAE,gBAAgB,CAAC;QAAC,IAAI,EAAE,IAAI,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAUlE,yCAAyC;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIlF;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzE,8BAA8B;IACxB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ3D"}
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 — and once decision tokens land
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
- `"${this.data.input.action ?? this.id}" within the timeout. ` +
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
  *
@@ -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,CAsIpD,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"}
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
  },
@@ -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
  *
@@ -1 +1 @@
1
- {"version":3,"file":"released.d.ts","sourceRoot":"","sources":["../src/released.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,yIAenB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA4BzC,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAuzFtD,CAAC"}
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"}