@deliverd/sdk 0.8.1 → 0.8.2
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 +562 -562
- package/dist/messages.d.ts.map +1 -1
- package/dist/messages.js +84 -5
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +413 -0
- package/package.json +55 -55
- package/src/approvals.ts +322 -322
- package/src/collections.ts +236 -236
- package/src/dev.ts +761 -761
- package/src/duration.ts +21 -21
- package/src/errors.ts +62 -62
- package/src/flows.ts +222 -222
- package/src/gates.ts +230 -230
- package/src/http.ts +217 -217
- package/src/index.ts +443 -443
- package/src/messages.ts +161 -82
- package/src/paging.ts +64 -64
- package/src/released.ts +2072 -1658
- package/src/reports.ts +490 -490
- package/src/reviews.ts +225 -225
- package/src/types.ts +838 -838
- package/src/webhooks.ts +98 -98
package/src/duration.ts
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* `expiresIn: "4h"` rather than an ISO timestamp the caller has to compute.
|
|
3
|
-
*
|
|
4
|
-
* Milliseconds are accepted too, because a number is what a timer takes and
|
|
5
|
-
* making somebody write `"3600000ms"` would be the kind of ceremony this SDK
|
|
6
|
-
* exists to remove.
|
|
7
|
-
*/
|
|
8
|
-
export type Duration = number | `${number}${"s" | "m" | "h" | "d"}`;
|
|
9
|
-
|
|
10
|
-
const UNITS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
|
|
11
|
-
|
|
12
|
-
export function durationMs(value: Duration): number {
|
|
13
|
-
if (typeof value === "number") return value;
|
|
14
|
-
const match = /^(\d+(?:\.\d+)?)([smhd])$/.exec(value.trim());
|
|
15
|
-
if (!match) {
|
|
16
|
-
throw new TypeError(
|
|
17
|
-
`Could not read "${value}" as a duration. Use a number of milliseconds, or a string like "30m", "4h" or "2d".`
|
|
18
|
-
);
|
|
19
|
-
}
|
|
20
|
-
return Number(match[1]) * UNITS[match[2] as keyof typeof UNITS];
|
|
21
|
-
}
|
|
1
|
+
/**
|
|
2
|
+
* `expiresIn: "4h"` rather than an ISO timestamp the caller has to compute.
|
|
3
|
+
*
|
|
4
|
+
* Milliseconds are accepted too, because a number is what a timer takes and
|
|
5
|
+
* making somebody write `"3600000ms"` would be the kind of ceremony this SDK
|
|
6
|
+
* exists to remove.
|
|
7
|
+
*/
|
|
8
|
+
export type Duration = number | `${number}${"s" | "m" | "h" | "d"}`;
|
|
9
|
+
|
|
10
|
+
const UNITS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
|
|
11
|
+
|
|
12
|
+
export function durationMs(value: Duration): number {
|
|
13
|
+
if (typeof value === "number") return value;
|
|
14
|
+
const match = /^(\d+(?:\.\d+)?)([smhd])$/.exec(value.trim());
|
|
15
|
+
if (!match) {
|
|
16
|
+
throw new TypeError(
|
|
17
|
+
`Could not read "${value}" as a duration. Use a number of milliseconds, or a string like "30m", "4h" or "2d".`
|
|
18
|
+
);
|
|
19
|
+
}
|
|
20
|
+
return Number(match[1]) * UNITS[match[2] as keyof typeof UNITS];
|
|
21
|
+
}
|
package/src/errors.ts
CHANGED
|
@@ -1,62 +1,62 @@
|
|
|
1
|
-
import { explain } from "./messages.js";
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
* Every failure the SDK raises, with the API's own code on it.
|
|
5
|
-
*
|
|
6
|
-
* One class rather than a hierarchy: callers branch on `code`, which is the
|
|
7
|
-
* string the API document lists, and a `instanceof` tree would make that the
|
|
8
|
-
* second way to ask the same question. The helpers below name the handful of
|
|
9
|
-
* cases worth branching on so nobody has to memorise the codes.
|
|
10
|
-
*/
|
|
11
|
-
export class DeliverdError extends Error {
|
|
12
|
-
/** The one thing to do next, when we know it. Also the tail of `message`. */
|
|
13
|
-
readonly hint?: string;
|
|
14
|
-
|
|
15
|
-
constructor(
|
|
16
|
-
/** HTTP status, or 0 when the request never got a response. */
|
|
17
|
-
public readonly status: number,
|
|
18
|
-
/** The API's error code: `not_found`, `rate_limited`, `self_approval`… */
|
|
19
|
-
public readonly code: string,
|
|
20
|
-
message: string,
|
|
21
|
-
/** Whatever the API attached — validation issues, the unknown approvers. */
|
|
22
|
-
public readonly details?: unknown,
|
|
23
|
-
options?: { cause?: unknown }
|
|
24
|
-
) {
|
|
25
|
-
const explained = explain(code, message);
|
|
26
|
-
super(explained.message, options);
|
|
27
|
-
this.name = "DeliverdError";
|
|
28
|
-
this.hint = explained.hint;
|
|
29
|
-
}
|
|
30
|
-
|
|
31
|
-
/** The key is missing, wrong, or lacks the scope the call needs. */
|
|
32
|
-
get isAuth(): boolean {
|
|
33
|
-
return this.status === 401 || this.status === 403;
|
|
34
|
-
}
|
|
35
|
-
|
|
36
|
-
/** Slow down; the client already retried and gave up. */
|
|
37
|
-
get isRateLimit(): boolean {
|
|
38
|
-
return this.status === 429;
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
/** Nothing there, or nothing this key may see. */
|
|
42
|
-
get isNotFound(): boolean {
|
|
43
|
-
return this.status === 404;
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
/**
|
|
47
|
-
* The request was fine and the state was not: someone published between
|
|
48
|
-
* your read and your write, a version is awaiting approval, a question was
|
|
49
|
-
* already answered. Re-read and try again.
|
|
50
|
-
*/
|
|
51
|
-
get isConflict(): boolean {
|
|
52
|
-
return this.status === 409;
|
|
53
|
-
}
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
/** Thrown when a wait is abandoned rather than answered. */
|
|
57
|
-
export class DeliverdTimeoutError extends DeliverdError {
|
|
58
|
-
constructor(message: string) {
|
|
59
|
-
super(0, "timeout", message);
|
|
60
|
-
this.name = "DeliverdTimeoutError";
|
|
61
|
-
}
|
|
62
|
-
}
|
|
1
|
+
import { explain } from "./messages.js";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Every failure the SDK raises, with the API's own code on it.
|
|
5
|
+
*
|
|
6
|
+
* One class rather than a hierarchy: callers branch on `code`, which is the
|
|
7
|
+
* string the API document lists, and a `instanceof` tree would make that the
|
|
8
|
+
* second way to ask the same question. The helpers below name the handful of
|
|
9
|
+
* cases worth branching on so nobody has to memorise the codes.
|
|
10
|
+
*/
|
|
11
|
+
export class DeliverdError extends Error {
|
|
12
|
+
/** The one thing to do next, when we know it. Also the tail of `message`. */
|
|
13
|
+
readonly hint?: string;
|
|
14
|
+
|
|
15
|
+
constructor(
|
|
16
|
+
/** HTTP status, or 0 when the request never got a response. */
|
|
17
|
+
public readonly status: number,
|
|
18
|
+
/** The API's error code: `not_found`, `rate_limited`, `self_approval`… */
|
|
19
|
+
public readonly code: string,
|
|
20
|
+
message: string,
|
|
21
|
+
/** Whatever the API attached — validation issues, the unknown approvers. */
|
|
22
|
+
public readonly details?: unknown,
|
|
23
|
+
options?: { cause?: unknown }
|
|
24
|
+
) {
|
|
25
|
+
const explained = explain(code, message);
|
|
26
|
+
super(explained.message, options);
|
|
27
|
+
this.name = "DeliverdError";
|
|
28
|
+
this.hint = explained.hint;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** The key is missing, wrong, or lacks the scope the call needs. */
|
|
32
|
+
get isAuth(): boolean {
|
|
33
|
+
return this.status === 401 || this.status === 403;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** Slow down; the client already retried and gave up. */
|
|
37
|
+
get isRateLimit(): boolean {
|
|
38
|
+
return this.status === 429;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Nothing there, or nothing this key may see. */
|
|
42
|
+
get isNotFound(): boolean {
|
|
43
|
+
return this.status === 404;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* The request was fine and the state was not: someone published between
|
|
48
|
+
* your read and your write, a version is awaiting approval, a question was
|
|
49
|
+
* already answered. Re-read and try again.
|
|
50
|
+
*/
|
|
51
|
+
get isConflict(): boolean {
|
|
52
|
+
return this.status === 409;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** Thrown when a wait is abandoned rather than answered. */
|
|
57
|
+
export class DeliverdTimeoutError extends DeliverdError {
|
|
58
|
+
constructor(message: string) {
|
|
59
|
+
super(0, "timeout", message);
|
|
60
|
+
this.name = "DeliverdTimeoutError";
|
|
61
|
+
}
|
|
62
|
+
}
|
package/src/flows.ts
CHANGED
|
@@ -1,222 +1,222 @@
|
|
|
1
|
-
import { listOrCollect, type PageOf } from "./paging.js";
|
|
2
|
-
import type { HttpClient } from "./http.js";
|
|
3
|
-
import type { CreateFlowInput, EvidencePack, FlowData, ListFlowsInput } from "./types.js";
|
|
4
|
-
/*
|
|
5
|
-
* Type-only, and therefore erased: `index.ts` imports this file at runtime,
|
|
6
|
-
* and a value import back would be a cycle. What the handle needs from the
|
|
7
|
-
* client is its three primitives with their real signatures, so that
|
|
8
|
-
* `flow.approve({…})` is checked exactly as `deliverd.approve({…})` is.
|
|
9
|
-
*/
|
|
10
|
-
import type {
|
|
11
|
-
ApproveOptions,
|
|
12
|
-
CollectOptions,
|
|
13
|
-
Decision,
|
|
14
|
-
ReviewOptions,
|
|
15
|
-
ReviewOutcome,
|
|
16
|
-
} from "./index.js";
|
|
17
|
-
import type { CollectedAnswers } from "./types.js";
|
|
18
|
-
|
|
19
|
-
/**
|
|
20
|
-
* A flow: the thread that ties one job's approvals, reviews, collections and
|
|
21
|
-
* publishes together.
|
|
22
|
-
*
|
|
23
|
-
* The reason it exists in this SDK rather than only in the API is the handle
|
|
24
|
-
* below. An agent doing a multi-step job would otherwise carry a `flowId`
|
|
25
|
-
* through every call and pass it by hand each time — which works right up
|
|
26
|
-
* until one call is written without it, and that step is then missing from
|
|
27
|
-
* the history with nothing to say so. `flow.approve()` cannot forget.
|
|
28
|
-
*
|
|
29
|
-
* It groups and nothing else. Nothing waits on a flow; nothing is blocked by
|
|
30
|
-
* one; there are no steps to declare up front. Do the work in the order you
|
|
31
|
-
* want it done and name the flow as you go.
|
|
32
|
-
*/
|
|
33
|
-
|
|
34
|
-
/** The three primitives a flow can start on your behalf, with their real signatures. */
|
|
35
|
-
export interface FlowPrimitives {
|
|
36
|
-
approve(options: ApproveOptions): Promise<Decision>;
|
|
37
|
-
review(options: ReviewOptions): Promise<ReviewOutcome>;
|
|
38
|
-
collect(options: CollectOptions): Promise<CollectedAnswers>;
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
export class Flow {
|
|
42
|
-
constructor(
|
|
43
|
-
private readonly http: HttpClient,
|
|
44
|
-
private data: FlowData,
|
|
45
|
-
private readonly client: FlowPrimitives
|
|
46
|
-
) {}
|
|
47
|
-
|
|
48
|
-
get id(): string { return this.data.id; }
|
|
49
|
-
get status(): FlowData["status"] { return this.data.status; }
|
|
50
|
-
/** The timeline page a person can open. */
|
|
51
|
-
get url(): string { return this.data.url; }
|
|
52
|
-
get title(): string { return this.data.title; }
|
|
53
|
-
get members(): FlowData["members"] { return this.data.members; }
|
|
54
|
-
get timeline(): NonNullable<FlowData["timeline"]> { return this.data.timeline ?? []; }
|
|
55
|
-
get memberCount(): number { return this.data.memberCount; }
|
|
56
|
-
get openCount(): number { return this.data.openCount; }
|
|
57
|
-
|
|
58
|
-
get open(): boolean { return this.data.status === "open"; }
|
|
59
|
-
get complete(): boolean { return this.data.status === "complete"; }
|
|
60
|
-
get cancelled(): boolean { return this.data.status === "cancelled"; }
|
|
61
|
-
|
|
62
|
-
/**
|
|
63
|
-
* Nothing in it is waiting on anybody *at this moment*.
|
|
64
|
-
*
|
|
65
|
-
* Not a claim that the job is finished — you may be about to add the next
|
|
66
|
-
* step, and an empty flow is never settled. Branch on it to decide whether
|
|
67
|
-
* to move on; call `complete()` to say the work is over.
|
|
68
|
-
*/
|
|
69
|
-
get allSettled(): boolean { return this.data.allSettled; }
|
|
70
|
-
|
|
71
|
-
toJSON(): FlowData { return this.data; }
|
|
72
|
-
|
|
73
|
-
async refresh(signal?: AbortSignal): Promise<this> {
|
|
74
|
-
this.data = await this.http.request<FlowData>({
|
|
75
|
-
method: "GET",
|
|
76
|
-
path: `/flows/${this.data.id}`,
|
|
77
|
-
signal,
|
|
78
|
-
});
|
|
79
|
-
return this;
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
/**
|
|
83
|
-
* Ask permission, inside this flow. Exactly `deliverd.approve()` with the
|
|
84
|
-
* flow already named — which is the point: a `flowId` passed by hand at
|
|
85
|
-
* four call sites is one that gets left off the fifth.
|
|
86
|
-
*/
|
|
87
|
-
approve(options: Omit<ApproveOptions, "flowId">): Promise<Decision> {
|
|
88
|
-
return this.client.approve({ ...options, flowId: this.data.id });
|
|
89
|
-
}
|
|
90
|
-
|
|
91
|
-
/** Ask for judgement, inside this flow. */
|
|
92
|
-
review(options: Omit<ReviewOptions, "flowId">): Promise<ReviewOutcome> {
|
|
93
|
-
return this.client.review({ ...options, flowId: this.data.id });
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
/** Ask for facts, inside this flow. */
|
|
97
|
-
collect(options: Omit<CollectOptions, "flowId">): Promise<CollectedAnswers> {
|
|
98
|
-
return this.client.collect({ ...options, flowId: this.data.id });
|
|
99
|
-
}
|
|
100
|
-
|
|
101
|
-
/**
|
|
102
|
-
* The whole record of this flow: every step with who was asked and what they
|
|
103
|
-
* said, and the timeline across all of it.
|
|
104
|
-
*
|
|
105
|
-
* What to hand over when somebody asks you to show your working. Needs every
|
|
106
|
-
* read scope, because it contains everything.
|
|
107
|
-
*/
|
|
108
|
-
evidence(signal?: AbortSignal): Promise<EvidencePack> {
|
|
109
|
-
return this.http.request<EvidencePack>({
|
|
110
|
-
method: "GET",
|
|
111
|
-
path: `/flows/${this.data.id}/evidence`,
|
|
112
|
-
signal,
|
|
113
|
-
});
|
|
114
|
-
}
|
|
115
|
-
|
|
116
|
-
/**
|
|
117
|
-
* Say the work is done. It stops taking new members from here.
|
|
118
|
-
*
|
|
119
|
-
* Named `close()` rather than `complete()` so it does not collide with the
|
|
120
|
-
* `complete` getter above, which every other primitive in this SDK also
|
|
121
|
-
* has; `flow.complete` asks, `flow.close()` decides.
|
|
122
|
-
*
|
|
123
|
-
* Allowed with steps still outstanding, and how many is recorded — a flow
|
|
124
|
-
* that could not be closed until every reviewer replied would be one that
|
|
125
|
-
* stayed open for ever.
|
|
126
|
-
*/
|
|
127
|
-
async close(signal?: AbortSignal): Promise<this> {
|
|
128
|
-
this.data = await this.http.request<FlowData>({
|
|
129
|
-
method: "POST",
|
|
130
|
-
path: `/flows/${this.data.id}/complete`,
|
|
131
|
-
signal,
|
|
132
|
-
});
|
|
133
|
-
return this;
|
|
134
|
-
}
|
|
135
|
-
|
|
136
|
-
/** Call it off. The flow and its members stay as evidence; nothing inside is cancelled. */
|
|
137
|
-
async cancel(signal?: AbortSignal): Promise<this> {
|
|
138
|
-
this.data = await this.http.request<FlowData>({
|
|
139
|
-
method: "POST",
|
|
140
|
-
path: `/flows/${this.data.id}/cancel`,
|
|
141
|
-
signal,
|
|
142
|
-
});
|
|
143
|
-
return this;
|
|
144
|
-
}
|
|
145
|
-
}
|
|
146
|
-
|
|
147
|
-
export class Flows {
|
|
148
|
-
constructor(
|
|
149
|
-
private readonly http: HttpClient,
|
|
150
|
-
private readonly client: FlowPrimitives
|
|
151
|
-
) {}
|
|
152
|
-
|
|
153
|
-
async create(input: CreateFlowInput, signal?: AbortSignal): Promise<Flow> {
|
|
154
|
-
const data = await this.http.request<FlowData>({
|
|
155
|
-
method: "POST",
|
|
156
|
-
path: "/flows",
|
|
157
|
-
body: input,
|
|
158
|
-
signal,
|
|
159
|
-
});
|
|
160
|
-
return new Flow(this.http, data, this.client);
|
|
161
|
-
}
|
|
162
|
-
|
|
163
|
-
async get(id: string, signal?: AbortSignal): Promise<Flow> {
|
|
164
|
-
const data = await this.http.request<FlowData>({
|
|
165
|
-
method: "GET",
|
|
166
|
-
path: `/flows/${id}`,
|
|
167
|
-
signal,
|
|
168
|
-
});
|
|
169
|
-
return new Flow(this.http, data, this.client);
|
|
170
|
-
}
|
|
171
|
-
|
|
172
|
-
/**
|
|
173
|
-
* The organisation's flows, newest first.
|
|
174
|
-
*
|
|
175
|
-
* With no `limit` this is every one of them: the API says where each page
|
|
176
|
-
* stopped and this follows the cursor to the end. With a `limit` it is one
|
|
177
|
-
* page of that size, and `listPage` hands back the cursor to continue from.
|
|
178
|
-
*/
|
|
179
|
-
async list(input: ListFlowsInput = {}, signal?: AbortSignal): Promise<Flow[]> {
|
|
180
|
-
return listOrCollect(input, async (q: { limit?: number; cursor?: string }) => {
|
|
181
|
-
const page = await this.listPage({ ...input, ...q }, signal);
|
|
182
|
-
return { items: page.items, nextCursor: page.nextCursor };
|
|
183
|
-
});
|
|
184
|
-
}
|
|
185
|
-
|
|
186
|
-
/** One page, and the cursor to continue from — null when it is the end. */
|
|
187
|
-
async listPage(
|
|
188
|
-
input: ListFlowsInput = {},
|
|
189
|
-
signal?: AbortSignal
|
|
190
|
-
): Promise<PageOf<Flow>> {
|
|
191
|
-
const { flows, nextCursor } = await this.http.request<{
|
|
192
|
-
flows: FlowData[];
|
|
193
|
-
nextCursor: string | null;
|
|
194
|
-
}>({
|
|
195
|
-
method: "GET",
|
|
196
|
-
path: "/flows",
|
|
197
|
-
query: { status: input.status, externalId: input.externalId, limit: input.limit, cursor: input.cursor },
|
|
198
|
-
signal,
|
|
199
|
-
});
|
|
200
|
-
return { items: flows.map((f) => new Flow(this.http, f, this.client)), nextCursor };
|
|
201
|
-
}
|
|
202
|
-
|
|
203
|
-
/** The same job as before, when there was one — so a restart extends it rather than starting a second. */
|
|
204
|
-
async findByExternalId(externalId: string, signal?: AbortSignal): Promise<Flow | null> {
|
|
205
|
-
const found = await this.list({ externalId, limit: 1 }, signal);
|
|
206
|
-
return found[0] ?? null;
|
|
207
|
-
}
|
|
208
|
-
|
|
209
|
-
/**
|
|
210
|
-
* The flow for this reference, started if it does not exist yet.
|
|
211
|
-
*
|
|
212
|
-
* What a restartable agent actually wants: one line that is correct on the
|
|
213
|
-
* first run and on the fourth. Without it the caller writes the lookup, the
|
|
214
|
-
* branch and the create by hand, and a crash between the lookup and the
|
|
215
|
-
* create leaves two flows for one job.
|
|
216
|
-
*/
|
|
217
|
-
async resume(input: CreateFlowInput & { externalId: string }, signal?: AbortSignal): Promise<Flow> {
|
|
218
|
-
const existing = await this.findByExternalId(input.externalId, signal);
|
|
219
|
-
if (existing && existing.open) return existing;
|
|
220
|
-
return this.create(input, signal);
|
|
221
|
-
}
|
|
222
|
-
}
|
|
1
|
+
import { listOrCollect, type PageOf } from "./paging.js";
|
|
2
|
+
import type { HttpClient } from "./http.js";
|
|
3
|
+
import type { CreateFlowInput, EvidencePack, FlowData, ListFlowsInput } from "./types.js";
|
|
4
|
+
/*
|
|
5
|
+
* Type-only, and therefore erased: `index.ts` imports this file at runtime,
|
|
6
|
+
* and a value import back would be a cycle. What the handle needs from the
|
|
7
|
+
* client is its three primitives with their real signatures, so that
|
|
8
|
+
* `flow.approve({…})` is checked exactly as `deliverd.approve({…})` is.
|
|
9
|
+
*/
|
|
10
|
+
import type {
|
|
11
|
+
ApproveOptions,
|
|
12
|
+
CollectOptions,
|
|
13
|
+
Decision,
|
|
14
|
+
ReviewOptions,
|
|
15
|
+
ReviewOutcome,
|
|
16
|
+
} from "./index.js";
|
|
17
|
+
import type { CollectedAnswers } from "./types.js";
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* A flow: the thread that ties one job's approvals, reviews, collections and
|
|
21
|
+
* publishes together.
|
|
22
|
+
*
|
|
23
|
+
* The reason it exists in this SDK rather than only in the API is the handle
|
|
24
|
+
* below. An agent doing a multi-step job would otherwise carry a `flowId`
|
|
25
|
+
* through every call and pass it by hand each time — which works right up
|
|
26
|
+
* until one call is written without it, and that step is then missing from
|
|
27
|
+
* the history with nothing to say so. `flow.approve()` cannot forget.
|
|
28
|
+
*
|
|
29
|
+
* It groups and nothing else. Nothing waits on a flow; nothing is blocked by
|
|
30
|
+
* one; there are no steps to declare up front. Do the work in the order you
|
|
31
|
+
* want it done and name the flow as you go.
|
|
32
|
+
*/
|
|
33
|
+
|
|
34
|
+
/** The three primitives a flow can start on your behalf, with their real signatures. */
|
|
35
|
+
export interface FlowPrimitives {
|
|
36
|
+
approve(options: ApproveOptions): Promise<Decision>;
|
|
37
|
+
review(options: ReviewOptions): Promise<ReviewOutcome>;
|
|
38
|
+
collect(options: CollectOptions): Promise<CollectedAnswers>;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export class Flow {
|
|
42
|
+
constructor(
|
|
43
|
+
private readonly http: HttpClient,
|
|
44
|
+
private data: FlowData,
|
|
45
|
+
private readonly client: FlowPrimitives
|
|
46
|
+
) {}
|
|
47
|
+
|
|
48
|
+
get id(): string { return this.data.id; }
|
|
49
|
+
get status(): FlowData["status"] { return this.data.status; }
|
|
50
|
+
/** The timeline page a person can open. */
|
|
51
|
+
get url(): string { return this.data.url; }
|
|
52
|
+
get title(): string { return this.data.title; }
|
|
53
|
+
get members(): FlowData["members"] { return this.data.members; }
|
|
54
|
+
get timeline(): NonNullable<FlowData["timeline"]> { return this.data.timeline ?? []; }
|
|
55
|
+
get memberCount(): number { return this.data.memberCount; }
|
|
56
|
+
get openCount(): number { return this.data.openCount; }
|
|
57
|
+
|
|
58
|
+
get open(): boolean { return this.data.status === "open"; }
|
|
59
|
+
get complete(): boolean { return this.data.status === "complete"; }
|
|
60
|
+
get cancelled(): boolean { return this.data.status === "cancelled"; }
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Nothing in it is waiting on anybody *at this moment*.
|
|
64
|
+
*
|
|
65
|
+
* Not a claim that the job is finished — you may be about to add the next
|
|
66
|
+
* step, and an empty flow is never settled. Branch on it to decide whether
|
|
67
|
+
* to move on; call `complete()` to say the work is over.
|
|
68
|
+
*/
|
|
69
|
+
get allSettled(): boolean { return this.data.allSettled; }
|
|
70
|
+
|
|
71
|
+
toJSON(): FlowData { return this.data; }
|
|
72
|
+
|
|
73
|
+
async refresh(signal?: AbortSignal): Promise<this> {
|
|
74
|
+
this.data = await this.http.request<FlowData>({
|
|
75
|
+
method: "GET",
|
|
76
|
+
path: `/flows/${this.data.id}`,
|
|
77
|
+
signal,
|
|
78
|
+
});
|
|
79
|
+
return this;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Ask permission, inside this flow. Exactly `deliverd.approve()` with the
|
|
84
|
+
* flow already named — which is the point: a `flowId` passed by hand at
|
|
85
|
+
* four call sites is one that gets left off the fifth.
|
|
86
|
+
*/
|
|
87
|
+
approve(options: Omit<ApproveOptions, "flowId">): Promise<Decision> {
|
|
88
|
+
return this.client.approve({ ...options, flowId: this.data.id });
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** Ask for judgement, inside this flow. */
|
|
92
|
+
review(options: Omit<ReviewOptions, "flowId">): Promise<ReviewOutcome> {
|
|
93
|
+
return this.client.review({ ...options, flowId: this.data.id });
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Ask for facts, inside this flow. */
|
|
97
|
+
collect(options: Omit<CollectOptions, "flowId">): Promise<CollectedAnswers> {
|
|
98
|
+
return this.client.collect({ ...options, flowId: this.data.id });
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* The whole record of this flow: every step with who was asked and what they
|
|
103
|
+
* said, and the timeline across all of it.
|
|
104
|
+
*
|
|
105
|
+
* What to hand over when somebody asks you to show your working. Needs every
|
|
106
|
+
* read scope, because it contains everything.
|
|
107
|
+
*/
|
|
108
|
+
evidence(signal?: AbortSignal): Promise<EvidencePack> {
|
|
109
|
+
return this.http.request<EvidencePack>({
|
|
110
|
+
method: "GET",
|
|
111
|
+
path: `/flows/${this.data.id}/evidence`,
|
|
112
|
+
signal,
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Say the work is done. It stops taking new members from here.
|
|
118
|
+
*
|
|
119
|
+
* Named `close()` rather than `complete()` so it does not collide with the
|
|
120
|
+
* `complete` getter above, which every other primitive in this SDK also
|
|
121
|
+
* has; `flow.complete` asks, `flow.close()` decides.
|
|
122
|
+
*
|
|
123
|
+
* Allowed with steps still outstanding, and how many is recorded — a flow
|
|
124
|
+
* that could not be closed until every reviewer replied would be one that
|
|
125
|
+
* stayed open for ever.
|
|
126
|
+
*/
|
|
127
|
+
async close(signal?: AbortSignal): Promise<this> {
|
|
128
|
+
this.data = await this.http.request<FlowData>({
|
|
129
|
+
method: "POST",
|
|
130
|
+
path: `/flows/${this.data.id}/complete`,
|
|
131
|
+
signal,
|
|
132
|
+
});
|
|
133
|
+
return this;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** Call it off. The flow and its members stay as evidence; nothing inside is cancelled. */
|
|
137
|
+
async cancel(signal?: AbortSignal): Promise<this> {
|
|
138
|
+
this.data = await this.http.request<FlowData>({
|
|
139
|
+
method: "POST",
|
|
140
|
+
path: `/flows/${this.data.id}/cancel`,
|
|
141
|
+
signal,
|
|
142
|
+
});
|
|
143
|
+
return this;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
export class Flows {
|
|
148
|
+
constructor(
|
|
149
|
+
private readonly http: HttpClient,
|
|
150
|
+
private readonly client: FlowPrimitives
|
|
151
|
+
) {}
|
|
152
|
+
|
|
153
|
+
async create(input: CreateFlowInput, signal?: AbortSignal): Promise<Flow> {
|
|
154
|
+
const data = await this.http.request<FlowData>({
|
|
155
|
+
method: "POST",
|
|
156
|
+
path: "/flows",
|
|
157
|
+
body: input,
|
|
158
|
+
signal,
|
|
159
|
+
});
|
|
160
|
+
return new Flow(this.http, data, this.client);
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
async get(id: string, signal?: AbortSignal): Promise<Flow> {
|
|
164
|
+
const data = await this.http.request<FlowData>({
|
|
165
|
+
method: "GET",
|
|
166
|
+
path: `/flows/${id}`,
|
|
167
|
+
signal,
|
|
168
|
+
});
|
|
169
|
+
return new Flow(this.http, data, this.client);
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* The organisation's flows, newest first.
|
|
174
|
+
*
|
|
175
|
+
* With no `limit` this is every one of them: the API says where each page
|
|
176
|
+
* stopped and this follows the cursor to the end. With a `limit` it is one
|
|
177
|
+
* page of that size, and `listPage` hands back the cursor to continue from.
|
|
178
|
+
*/
|
|
179
|
+
async list(input: ListFlowsInput = {}, signal?: AbortSignal): Promise<Flow[]> {
|
|
180
|
+
return listOrCollect(input, async (q: { limit?: number; cursor?: string }) => {
|
|
181
|
+
const page = await this.listPage({ ...input, ...q }, signal);
|
|
182
|
+
return { items: page.items, nextCursor: page.nextCursor };
|
|
183
|
+
});
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** One page, and the cursor to continue from — null when it is the end. */
|
|
187
|
+
async listPage(
|
|
188
|
+
input: ListFlowsInput = {},
|
|
189
|
+
signal?: AbortSignal
|
|
190
|
+
): Promise<PageOf<Flow>> {
|
|
191
|
+
const { flows, nextCursor } = await this.http.request<{
|
|
192
|
+
flows: FlowData[];
|
|
193
|
+
nextCursor: string | null;
|
|
194
|
+
}>({
|
|
195
|
+
method: "GET",
|
|
196
|
+
path: "/flows",
|
|
197
|
+
query: { status: input.status, externalId: input.externalId, limit: input.limit, cursor: input.cursor },
|
|
198
|
+
signal,
|
|
199
|
+
});
|
|
200
|
+
return { items: flows.map((f) => new Flow(this.http, f, this.client)), nextCursor };
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/** The same job as before, when there was one — so a restart extends it rather than starting a second. */
|
|
204
|
+
async findByExternalId(externalId: string, signal?: AbortSignal): Promise<Flow | null> {
|
|
205
|
+
const found = await this.list({ externalId, limit: 1 }, signal);
|
|
206
|
+
return found[0] ?? null;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* The flow for this reference, started if it does not exist yet.
|
|
211
|
+
*
|
|
212
|
+
* What a restartable agent actually wants: one line that is correct on the
|
|
213
|
+
* first run and on the fourth. Without it the caller writes the lookup, the
|
|
214
|
+
* branch and the create by hand, and a crash between the lookup and the
|
|
215
|
+
* create leaves two flows for one job.
|
|
216
|
+
*/
|
|
217
|
+
async resume(input: CreateFlowInput & { externalId: string }, signal?: AbortSignal): Promise<Flow> {
|
|
218
|
+
const existing = await this.findByExternalId(input.externalId, signal);
|
|
219
|
+
if (existing && existing.open) return existing;
|
|
220
|
+
return this.create(input, signal);
|
|
221
|
+
}
|
|
222
|
+
}
|