@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/types.ts CHANGED
@@ -12,6 +12,91 @@
12
12
  export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled";
13
13
  export type ApprovalRisk = "low" | "medium" | "high" | "critical";
14
14
 
15
+ /**
16
+ * What a gate decision can be.
17
+ *
18
+ * Seven, and the extra four over `allowed | denied | pending` are worth the
19
+ * width. `allowed` and `denied` are what a *rule* said; the rest are what a
20
+ * *person* did about a request no rule settled. An action that went through
21
+ * because policy permitted it and one that went through because somebody
22
+ * agreed to it are not the same fact — the ratio between them is the number
23
+ * this whole layer exists to make computable — so collapsing them would throw
24
+ * away the distinction at the one place a caller can see it.
25
+ */
26
+ export type GateStatus =
27
+ | "allowed"
28
+ | "denied"
29
+ | "pending"
30
+ | "approved"
31
+ | "rejected"
32
+ | "expired"
33
+ | "cancelled";
34
+
35
+ /** What a person decided about a gate, once one has. */
36
+ export type GateOutcomeName = "approved" | "rejected" | "cancelled" | "expired";
37
+
38
+ export interface CreateGateInput {
39
+ /** The registered action you are about to perform: `finance.refund`. */
40
+ actionId: string;
41
+ /** The arguments you will actually execute with. Validated against the action's schema. */
42
+ input: Record<string, unknown>;
43
+ /**
44
+ * Your id for this unit of work — `refund:ord_8812`. **Required**, which no
45
+ * other create in this SDK is.
46
+ *
47
+ * Every other POST mints a random idempotency key per attempt, which guards a
48
+ * retried *request*. This guards a retried *decision*: a crashed agent that
49
+ * re-runs its refund step must re-read the answer it already got, not ask a
50
+ * second person about the same money. No id the SDK invented could know which
51
+ * two calls are the same attempt, so you name it.
52
+ */
53
+ externalId: string;
54
+ /** Where this is running, for rules that tell staging from production. */
55
+ environment?: string;
56
+ /** Why, shown to whoever is asked to decide. */
57
+ reason?: string;
58
+ flowId?: string;
59
+ }
60
+
61
+ export interface GateData {
62
+ id: string;
63
+ status: GateStatus;
64
+ /** The one to branch on: a rule permitted it, or a person agreed to it. */
65
+ allowed: boolean;
66
+ /** The input as the action's schema validated it — what to execute with. */
67
+ input: Record<string, unknown>;
68
+ /** Whether a rule decided this or a person did. */
69
+ basis: "policy" | "human";
70
+ reason: string | null;
71
+ /** The rule that decided, by name. Null when nothing matched. */
72
+ rule: string | null;
73
+ policyVersionId: string | null;
74
+ approvalId: string | null;
75
+ approvalUrl: string | null;
76
+ outcome: GateOutcomeName | null;
77
+ settledAt: string | null;
78
+ /** True when this call found a decision already made under your `externalId`. */
79
+ reused: boolean;
80
+ }
81
+
82
+ /**
83
+ * The answer, flattened — what `gate()` hands back.
84
+ *
85
+ * `allowed` is a boolean so `if (decision.allowed)` reads as the sentence it
86
+ * is; `status` is the narrowing union for a switch. The same pairing, for the
87
+ * same reason, as `Decision` on an approval.
88
+ */
89
+ export interface GateDecision {
90
+ allowed: boolean;
91
+ status: GateStatus;
92
+ reason: string | null;
93
+ rule: string | null;
94
+ input: Record<string, unknown>;
95
+ id: string;
96
+ approvalUrl: string | null;
97
+ gate: unknown;
98
+ }
99
+
15
100
  /** One line of evidence, as the approval page shows it. */
16
101
  export interface ApprovalFactor {
17
102
  label: string;
@@ -365,7 +450,11 @@ export type WebhookEventName =
365
450
  | "review.changes_requested"
366
451
  | "collection.requested"
367
452
  | "collection.completed"
368
- | "flow.completed";
453
+ | "flow.completed"
454
+ /** A gate refused. The only gate event that relays: an allow fires on every
455
+ * auto-allowed action, and an escalation already arrives as
456
+ * `approval.requested`. */
457
+ | "gate.denied";
369
458
 
370
459
  export interface WebhookEvent {
371
460
  event: WebhookEventName;