@deliverd/sdk 0.10.0 → 0.11.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
@@ -9,7 +9,7 @@
9
9
  * looking.
10
10
  */
11
11
 
12
- export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled";
12
+ export type ApprovalStatus = "pending" | "approved" | "rejected" | "changes_requested" | "expired" | "cancelled";
13
13
  export type ApprovalRisk = "low" | "medium" | "high" | "critical";
14
14
 
15
15
  /**
@@ -29,11 +29,123 @@ export type GateStatus =
29
29
  | "pending"
30
30
  | "approved"
31
31
  | "rejected"
32
+ | "changes_requested"
32
33
  | "expired"
33
- | "cancelled";
34
+ | "cancelled"
35
+ /** A person took the permission back before it was used. */
36
+ | "revoked"
37
+ /** The permission has been used. A further act needs a new gate. */
38
+ | "used";
34
39
 
35
40
  /** What a person decided about a gate, once one has. */
36
- export type GateOutcomeName = "approved" | "rejected" | "cancelled" | "expired";
41
+ export type GateOutcomeName = "approved" | "rejected" | "changes_requested" | "cancelled" | "expired";
42
+
43
+ /**
44
+ * What policy said, in the words agents are told: fixed when the gate is made.
45
+ * `status` is where it stands now; this is what it was.
46
+ */
47
+ export type GateDecisionName = "ALLOW" | "APPROVAL_REQUIRED" | "REVIEW_REQUIRED" | "DENY";
48
+
49
+ /** Where an act lands. Deliverd decides whether it is inside the organisation. */
50
+ export interface Destination {
51
+ /** `workspace`, `report`, `user`, `group`, `email`, `url`, `channel`, `repository`, … */
52
+ type: string;
53
+ id: string;
54
+ label?: string;
55
+ }
56
+
57
+ /**
58
+ * What an act is about. A Deliverd report version (the approval binds to that
59
+ * version and no other), or a file you hold, by its sha256.
60
+ */
61
+ export interface GateArtifactRef {
62
+ reportId?: string;
63
+ versionId?: string;
64
+ sha256?: string;
65
+ name?: string;
66
+ mimeType?: string;
67
+ size?: number;
68
+ uri?: string;
69
+ }
70
+
71
+ /** Who is asking, when you ask through a person's connection rather than an agent key. */
72
+ export interface GateAgentRef {
73
+ /** A Deliverd agent id. */
74
+ id?: string;
75
+ /** `openai_dot`, `openai_chatgpt`, `openai_codex`, `anthropic`, `google`, `custom`, … */
76
+ provider?: string;
77
+ /** Your id on that platform. */
78
+ externalId?: string;
79
+ name?: string;
80
+ }
81
+
82
+ /** The run a gate belongs to, found by its id or started. */
83
+ export interface GateExecutionRef {
84
+ providerExecutionId?: string;
85
+ objective?: string;
86
+ title?: string;
87
+ /** The run that delegated this one. */
88
+ parentFlowId?: string;
89
+ }
90
+
91
+ /** What a gate's permission covers. Every field is fixed when the gate is made. */
92
+ export interface GateScope {
93
+ destination: Destination | null;
94
+ /** Worked out by Deliverd, never taken from the request. */
95
+ recipientScope: "internal" | "external" | null;
96
+ classification: "public" | "internal" | "confidential" | "restricted" | null;
97
+ risk: ApprovalRisk | null;
98
+ artifact: {
99
+ kind: "report_version" | "external";
100
+ reportId: string | null;
101
+ versionId: string | null;
102
+ versionNumber: number | null;
103
+ sha256: string | null;
104
+ name: string | null;
105
+ mimeType: string | null;
106
+ size: number | null;
107
+ uri: string | null;
108
+ /** True when Deliverd holds the artifact and the hash is its own. */
109
+ verified: boolean;
110
+ } | null;
111
+ digest: string | null;
112
+ }
113
+
114
+ /**
115
+ * A receipt: what the agent reported doing with a permission, and how much of
116
+ * it Deliverd checked. `verified` only when Deliverd did the act itself;
117
+ * `hash_matched` when it checked the hash; otherwise `reported`.
118
+ */
119
+ export interface ExecutionReceipt {
120
+ id: string;
121
+ gateId: string;
122
+ phase: "started" | "completed" | "failed";
123
+ claimId: string | null;
124
+ executedAt: string | null;
125
+ artifactSha256: string | null;
126
+ destination: Destination | null;
127
+ result: Record<string, unknown>;
128
+ verification: "verified" | "hash_matched" | "reported";
129
+ detail: string | null;
130
+ reportedBy: string;
131
+ createdAt: string;
132
+ }
133
+
134
+ /** What you tell Deliverd you did. Recorded as your report, never as verified fact. */
135
+ export interface RecordExecutionInput {
136
+ /** `started` claims a use before you act; `completed` (the default) or `failed` reports the outcome. */
137
+ phase?: "started" | "completed" | "failed";
138
+ /** The id of your `started` receipt, when this finishes it. */
139
+ claimId?: string;
140
+ executedAt?: string;
141
+ /** Required when the permission names an artifact; a different hash is refused. */
142
+ artifactSha256?: string;
143
+ /** Where it landed. Must be where it was authorised to. */
144
+ destination?: Destination;
145
+ result?: Record<string, unknown>;
146
+ detail?: string;
147
+ agent?: GateAgentRef;
148
+ }
37
149
 
38
150
  export interface CreateGateInput {
39
151
  /** The registered action you are about to perform: `finance.refund`. */
@@ -56,6 +168,26 @@ export interface CreateGateInput {
56
168
  /** Why, shown to whoever is asked to decide. */
57
169
  reason?: string;
58
170
  flowId?: string;
171
+ /** What you are about to do, in a sentence a person will read. Same as `reason`. */
172
+ description?: string;
173
+ /** Where the act lands. An approval covers this destination and no other. */
174
+ destination?: Destination;
175
+ /** How sensitive the data is. Raises, never lowers, what Deliverd knows. */
176
+ classification?: "public" | "internal" | "confidential" | "restricted";
177
+ /** How risky you judge it. Raises, never lowers, the action's own risk. */
178
+ risk?: ApprovalRisk;
179
+ /** What the act is about. An approval covers this artifact and no other. */
180
+ artifact?: GateArtifactRef;
181
+ /** Who you are, when you ask through a person's connection. */
182
+ agent?: GateAgentRef;
183
+ /** The run this belongs to. Use instead of flowId. */
184
+ execution?: GateExecutionRef;
185
+ /** The gate this revises, after a person asked for changes. */
186
+ supersedesGateId?: string;
187
+ /** An https address for the gate's settlement and execution, signed. */
188
+ callbackUrl?: string;
189
+ /** Anything else a person deciding should see. Read by no rule. */
190
+ metadata?: Record<string, unknown>;
59
191
  }
60
192
 
61
193
  export interface GateData {
@@ -88,6 +220,30 @@ export interface GateData {
88
220
  settledAt: string | null;
89
221
  /** True when this call found a decision already made under your `externalId`. */
90
222
  reused: boolean;
223
+ /** What policy said, fixed when the gate was made. */
224
+ decision: GateDecisionName;
225
+ /**
226
+ * Whether you may act on this now: authorised, inside its window, with a use
227
+ * left, not revoked. `allowed` says it was ever authorised; this says it
228
+ * still is. The organisation's authorisation only — the platform you run on
229
+ * may still require its user's confirmation.
230
+ */
231
+ canExecute: boolean;
232
+ /** Why not, when `canExecute` is false. */
233
+ blockedBecause: string | null;
234
+ scope: GateScope;
235
+ authorisation: { validUntil: string | null; maxUses: number; usesRemaining: number };
236
+ actionId: string;
237
+ agentId: string | null;
238
+ flowId: string | null;
239
+ supersedesGateId: string | null;
240
+ description: string | null;
241
+ requestedBy: string;
242
+ createdAt: string | null;
243
+ /** Returned once, by the call that made the gate and named a callbackUrl. */
244
+ callbackSecret?: string;
245
+ /** On a single read: what has been reported against it. */
246
+ executions?: ExecutionReceipt[];
91
247
  }
92
248
 
93
249
  /**
@@ -251,10 +407,10 @@ export interface CreateApprovalInput {
251
407
  * not cover it.
252
408
  */
253
409
  export type Decision = {
254
- /** True only for an approval. False for rejected, expired and cancelled. */
410
+ /** True only for an approval. False for rejected, changes requested, expired and cancelled. */
255
411
  approved: boolean;
256
412
  /** For a switch, and for narrowing. */
257
- status: "approved" | "rejected" | "expired" | "cancelled";
413
+ status: "approved" | "rejected" | "changes_requested" | "expired" | "cancelled";
258
414
  /** Their reason, when they gave one. */
259
415
  note: string | null;
260
416
  /** Who decided, as a name rather than an id. Log it; put it in a message. */
@@ -500,6 +656,7 @@ export type WebhookEventName =
500
656
  | "approval.requested"
501
657
  | "approval.approved"
502
658
  | "approval.rejected"
659
+ | "approval.changes_requested"
503
660
  | "approval.expired"
504
661
  | "approval.escalated"
505
662
  | "approval.question"
@@ -513,7 +670,16 @@ export type WebhookEventName =
513
670
  /** A gate refused. The only gate event that relays: an allow fires on every
514
671
  * auto-allowed action, and an escalation already arrives as
515
672
  * `approval.requested`. */
516
- | "gate.denied";
673
+ | "gate.denied"
674
+ /** A gate's whole life. Opt-in: sent only to an endpoint that names them. */
675
+ | "gate.created"
676
+ | "gate.approved"
677
+ | "gate.rejected"
678
+ | "gate.changes_requested"
679
+ | "gate.expired"
680
+ | "gate.cancelled"
681
+ | "gate.revoked"
682
+ | "gate.executed";
517
683
 
518
684
  export interface WebhookEvent {
519
685
  event: WebhookEventName;
@@ -919,15 +1085,23 @@ export interface CallbackEnvelope {
919
1085
  event:
920
1086
  | "approval.approved"
921
1087
  | "approval.rejected"
1088
+ | "approval.changes_requested"
922
1089
  | "approval.expired"
923
1090
  | "approval.question"
924
1091
  | "review.approved"
925
1092
  | "review.changes_requested"
926
1093
  | "review.expired"
927
1094
  | "collection.completed"
928
- | "collection.expired";
1095
+ | "collection.expired"
1096
+ | "gate.approved"
1097
+ | "gate.rejected"
1098
+ | "gate.changes_requested"
1099
+ | "gate.expired"
1100
+ | "gate.cancelled"
1101
+ | "gate.revoked"
1102
+ | "gate.executed";
929
1103
  sentAt: string;
930
- requestType: "approval" | "review" | "collection";
1104
+ requestType: "approval" | "review" | "collection" | "gate";
931
1105
  requestId: string;
932
1106
  data: Record<string, unknown>;
933
1107
  }