@deliverd/sdk 0.2.0 → 0.4.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/README.md +98 -8
- package/dist/collections.d.ts +78 -0
- package/dist/collections.d.ts.map +1 -0
- package/dist/collections.js +170 -0
- package/dist/dev.d.ts +1 -1
- package/dist/dev.d.ts.map +1 -1
- package/dist/dev.js +195 -2
- package/dist/flows.d.ts +98 -0
- package/dist/flows.d.ts.map +1 -0
- package/dist/flows.js +136 -0
- package/dist/index.d.ts +47 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +62 -0
- package/dist/types.d.ts +174 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/collections.ts +214 -0
- package/src/dev.ts +223 -3
- package/src/flows.ts +185 -0
- package/src/index.ts +89 -0
- package/src/types.ts +200 -1
package/dist/flows.d.ts
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import type { HttpClient } from "./http.js";
|
|
2
|
+
import type { CreateFlowInput, FlowData, ListFlowsInput } from "./types.js";
|
|
3
|
+
import type { ApproveOptions, CollectOptions, Decision, ReviewOptions, ReviewOutcome } from "./index.js";
|
|
4
|
+
import type { CollectedAnswers } from "./types.js";
|
|
5
|
+
/**
|
|
6
|
+
* A flow: the thread that ties one job's approvals, reviews, collections and
|
|
7
|
+
* publishes together.
|
|
8
|
+
*
|
|
9
|
+
* The reason it exists in this SDK rather than only in the API is the handle
|
|
10
|
+
* below. An agent doing a multi-step job would otherwise carry a `flowId`
|
|
11
|
+
* through every call and pass it by hand each time — which works right up
|
|
12
|
+
* until one call is written without it, and that step is then missing from
|
|
13
|
+
* the history with nothing to say so. `flow.approve()` cannot forget.
|
|
14
|
+
*
|
|
15
|
+
* It groups and nothing else. Nothing waits on a flow; nothing is blocked by
|
|
16
|
+
* one; there are no steps to declare up front. Do the work in the order you
|
|
17
|
+
* want it done and name the flow as you go.
|
|
18
|
+
*/
|
|
19
|
+
/** The three primitives a flow can start on your behalf, with their real signatures. */
|
|
20
|
+
export interface FlowPrimitives {
|
|
21
|
+
approve(options: ApproveOptions): Promise<Decision>;
|
|
22
|
+
review(options: ReviewOptions): Promise<ReviewOutcome>;
|
|
23
|
+
collect(options: CollectOptions): Promise<CollectedAnswers>;
|
|
24
|
+
}
|
|
25
|
+
export declare class Flow {
|
|
26
|
+
private readonly http;
|
|
27
|
+
private data;
|
|
28
|
+
private readonly client;
|
|
29
|
+
constructor(http: HttpClient, data: FlowData, client: FlowPrimitives);
|
|
30
|
+
get id(): string;
|
|
31
|
+
get status(): FlowData["status"];
|
|
32
|
+
/** The timeline page a person can open. */
|
|
33
|
+
get url(): string;
|
|
34
|
+
get title(): string;
|
|
35
|
+
get members(): FlowData["members"];
|
|
36
|
+
get timeline(): NonNullable<FlowData["timeline"]>;
|
|
37
|
+
get memberCount(): number;
|
|
38
|
+
get openCount(): number;
|
|
39
|
+
get open(): boolean;
|
|
40
|
+
get complete(): boolean;
|
|
41
|
+
get cancelled(): boolean;
|
|
42
|
+
/**
|
|
43
|
+
* Nothing in it is waiting on anybody *at this moment*.
|
|
44
|
+
*
|
|
45
|
+
* Not a claim that the job is finished — you may be about to add the next
|
|
46
|
+
* step, and an empty flow is never settled. Branch on it to decide whether
|
|
47
|
+
* to move on; call `complete()` to say the work is over.
|
|
48
|
+
*/
|
|
49
|
+
get allSettled(): boolean;
|
|
50
|
+
toJSON(): FlowData;
|
|
51
|
+
refresh(signal?: AbortSignal): Promise<this>;
|
|
52
|
+
/**
|
|
53
|
+
* Ask permission, inside this flow. Exactly `deliverd.approve()` with the
|
|
54
|
+
* flow already named — which is the point: a `flowId` passed by hand at
|
|
55
|
+
* four call sites is one that gets left off the fifth.
|
|
56
|
+
*/
|
|
57
|
+
approve(options: Omit<ApproveOptions, "flowId">): Promise<Decision>;
|
|
58
|
+
/** Ask for judgement, inside this flow. */
|
|
59
|
+
review(options: Omit<ReviewOptions, "flowId">): Promise<ReviewOutcome>;
|
|
60
|
+
/** Ask for facts, inside this flow. */
|
|
61
|
+
collect(options: Omit<CollectOptions, "flowId">): Promise<CollectedAnswers>;
|
|
62
|
+
/**
|
|
63
|
+
* Say the work is done. It stops taking new members from here.
|
|
64
|
+
*
|
|
65
|
+
* Named `close()` rather than `complete()` so it does not collide with the
|
|
66
|
+
* `complete` getter above, which every other primitive in this SDK also
|
|
67
|
+
* has; `flow.complete` asks, `flow.close()` decides.
|
|
68
|
+
*
|
|
69
|
+
* Allowed with steps still outstanding, and how many is recorded — a flow
|
|
70
|
+
* that could not be closed until every reviewer replied would be one that
|
|
71
|
+
* stayed open for ever.
|
|
72
|
+
*/
|
|
73
|
+
close(signal?: AbortSignal): Promise<this>;
|
|
74
|
+
/** Call it off. The flow and its members stay as evidence; nothing inside is cancelled. */
|
|
75
|
+
cancel(signal?: AbortSignal): Promise<this>;
|
|
76
|
+
}
|
|
77
|
+
export declare class Flows {
|
|
78
|
+
private readonly http;
|
|
79
|
+
private readonly client;
|
|
80
|
+
constructor(http: HttpClient, client: FlowPrimitives);
|
|
81
|
+
create(input: CreateFlowInput, signal?: AbortSignal): Promise<Flow>;
|
|
82
|
+
get(id: string, signal?: AbortSignal): Promise<Flow>;
|
|
83
|
+
list(input?: ListFlowsInput, signal?: AbortSignal): Promise<Flow[]>;
|
|
84
|
+
/** The same job as before, when there was one — so a restart extends it rather than starting a second. */
|
|
85
|
+
findByExternalId(externalId: string, signal?: AbortSignal): Promise<Flow | null>;
|
|
86
|
+
/**
|
|
87
|
+
* The flow for this reference, started if it does not exist yet.
|
|
88
|
+
*
|
|
89
|
+
* What a restartable agent actually wants: one line that is correct on the
|
|
90
|
+
* first run and on the fourth. Without it the caller writes the lookup, the
|
|
91
|
+
* branch and the create by hand, and a crash between the lookup and the
|
|
92
|
+
* create leaves two flows for one job.
|
|
93
|
+
*/
|
|
94
|
+
resume(input: CreateFlowInput & {
|
|
95
|
+
externalId: string;
|
|
96
|
+
}, signal?: AbortSignal): Promise<Flow>;
|
|
97
|
+
}
|
|
98
|
+
//# sourceMappingURL=flows.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../src/flows.ts"],"names":[],"mappings":"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"}
|
package/dist/flows.js
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
export class Flow {
|
|
2
|
+
http;
|
|
3
|
+
data;
|
|
4
|
+
client;
|
|
5
|
+
constructor(http, data, client) {
|
|
6
|
+
this.http = http;
|
|
7
|
+
this.data = data;
|
|
8
|
+
this.client = client;
|
|
9
|
+
}
|
|
10
|
+
get id() { return this.data.id; }
|
|
11
|
+
get status() { return this.data.status; }
|
|
12
|
+
/** The timeline page a person can open. */
|
|
13
|
+
get url() { return this.data.url; }
|
|
14
|
+
get title() { return this.data.title; }
|
|
15
|
+
get members() { return this.data.members; }
|
|
16
|
+
get timeline() { return this.data.timeline ?? []; }
|
|
17
|
+
get memberCount() { return this.data.memberCount; }
|
|
18
|
+
get openCount() { return this.data.openCount; }
|
|
19
|
+
get open() { return this.data.status === "open"; }
|
|
20
|
+
get complete() { return this.data.status === "complete"; }
|
|
21
|
+
get cancelled() { return this.data.status === "cancelled"; }
|
|
22
|
+
/**
|
|
23
|
+
* Nothing in it is waiting on anybody *at this moment*.
|
|
24
|
+
*
|
|
25
|
+
* Not a claim that the job is finished — you may be about to add the next
|
|
26
|
+
* step, and an empty flow is never settled. Branch on it to decide whether
|
|
27
|
+
* to move on; call `complete()` to say the work is over.
|
|
28
|
+
*/
|
|
29
|
+
get allSettled() { return this.data.allSettled; }
|
|
30
|
+
toJSON() { return this.data; }
|
|
31
|
+
async refresh(signal) {
|
|
32
|
+
this.data = await this.http.request({
|
|
33
|
+
method: "GET",
|
|
34
|
+
path: `/flows/${this.data.id}`,
|
|
35
|
+
signal,
|
|
36
|
+
});
|
|
37
|
+
return this;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Ask permission, inside this flow. Exactly `deliverd.approve()` with the
|
|
41
|
+
* flow already named — which is the point: a `flowId` passed by hand at
|
|
42
|
+
* four call sites is one that gets left off the fifth.
|
|
43
|
+
*/
|
|
44
|
+
approve(options) {
|
|
45
|
+
return this.client.approve({ ...options, flowId: this.data.id });
|
|
46
|
+
}
|
|
47
|
+
/** Ask for judgement, inside this flow. */
|
|
48
|
+
review(options) {
|
|
49
|
+
return this.client.review({ ...options, flowId: this.data.id });
|
|
50
|
+
}
|
|
51
|
+
/** Ask for facts, inside this flow. */
|
|
52
|
+
collect(options) {
|
|
53
|
+
return this.client.collect({ ...options, flowId: this.data.id });
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Say the work is done. It stops taking new members from here.
|
|
57
|
+
*
|
|
58
|
+
* Named `close()` rather than `complete()` so it does not collide with the
|
|
59
|
+
* `complete` getter above, which every other primitive in this SDK also
|
|
60
|
+
* has; `flow.complete` asks, `flow.close()` decides.
|
|
61
|
+
*
|
|
62
|
+
* Allowed with steps still outstanding, and how many is recorded — a flow
|
|
63
|
+
* that could not be closed until every reviewer replied would be one that
|
|
64
|
+
* stayed open for ever.
|
|
65
|
+
*/
|
|
66
|
+
async close(signal) {
|
|
67
|
+
this.data = await this.http.request({
|
|
68
|
+
method: "POST",
|
|
69
|
+
path: `/flows/${this.data.id}/complete`,
|
|
70
|
+
signal,
|
|
71
|
+
});
|
|
72
|
+
return this;
|
|
73
|
+
}
|
|
74
|
+
/** Call it off. The flow and its members stay as evidence; nothing inside is cancelled. */
|
|
75
|
+
async cancel(signal) {
|
|
76
|
+
this.data = await this.http.request({
|
|
77
|
+
method: "POST",
|
|
78
|
+
path: `/flows/${this.data.id}/cancel`,
|
|
79
|
+
signal,
|
|
80
|
+
});
|
|
81
|
+
return this;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
export class Flows {
|
|
85
|
+
http;
|
|
86
|
+
client;
|
|
87
|
+
constructor(http, client) {
|
|
88
|
+
this.http = http;
|
|
89
|
+
this.client = client;
|
|
90
|
+
}
|
|
91
|
+
async create(input, signal) {
|
|
92
|
+
const data = await this.http.request({
|
|
93
|
+
method: "POST",
|
|
94
|
+
path: "/flows",
|
|
95
|
+
body: input,
|
|
96
|
+
signal,
|
|
97
|
+
});
|
|
98
|
+
return new Flow(this.http, data, this.client);
|
|
99
|
+
}
|
|
100
|
+
async get(id, signal) {
|
|
101
|
+
const data = await this.http.request({
|
|
102
|
+
method: "GET",
|
|
103
|
+
path: `/flows/${id}`,
|
|
104
|
+
signal,
|
|
105
|
+
});
|
|
106
|
+
return new Flow(this.http, data, this.client);
|
|
107
|
+
}
|
|
108
|
+
async list(input = {}, signal) {
|
|
109
|
+
const { flows } = await this.http.request({
|
|
110
|
+
method: "GET",
|
|
111
|
+
path: "/flows",
|
|
112
|
+
query: { status: input.status, externalId: input.externalId, limit: input.limit },
|
|
113
|
+
signal,
|
|
114
|
+
});
|
|
115
|
+
return flows.map((f) => new Flow(this.http, f, this.client));
|
|
116
|
+
}
|
|
117
|
+
/** The same job as before, when there was one — so a restart extends it rather than starting a second. */
|
|
118
|
+
async findByExternalId(externalId, signal) {
|
|
119
|
+
const found = await this.list({ externalId, limit: 1 }, signal);
|
|
120
|
+
return found[0] ?? null;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* The flow for this reference, started if it does not exist yet.
|
|
124
|
+
*
|
|
125
|
+
* What a restartable agent actually wants: one line that is correct on the
|
|
126
|
+
* first run and on the fourth. Without it the caller writes the lookup, the
|
|
127
|
+
* branch and the create by hand, and a crash between the lookup and the
|
|
128
|
+
* create leaves two flows for one job.
|
|
129
|
+
*/
|
|
130
|
+
async resume(input, signal) {
|
|
131
|
+
const existing = await this.findByExternalId(input.externalId, signal);
|
|
132
|
+
if (existing && existing.open)
|
|
133
|
+
return existing;
|
|
134
|
+
return this.create(input, signal);
|
|
135
|
+
}
|
|
136
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -2,13 +2,17 @@ import { HttpClient, type ClientOptions } from "./http.js";
|
|
|
2
2
|
import { Approvals, type WaitOptions } from "./approvals.js";
|
|
3
3
|
import { Comments, Reports } from "./reports.js";
|
|
4
4
|
import { Reviews, type ReviewWaitOptions } from "./reviews.js";
|
|
5
|
+
import { Collections, type CollectWaitOptions } from "./collections.js";
|
|
6
|
+
import { Flows } from "./flows.js";
|
|
5
7
|
import { Webhooks } from "./webhooks.js";
|
|
6
8
|
import { type DevelopmentOptions } from "./dev.js";
|
|
7
9
|
import { type Duration } from "./duration.js";
|
|
8
|
-
import type { CreateApprovalInput, CreateReviewInput, Decision, PublishReportInput, PublishResult, ReviewOutcome } from "./types.js";
|
|
10
|
+
import type { CollectedAnswers, CreateApprovalInput, CreateCollectionInput, CreateReviewInput, Decision, PublishReportInput, PublishResult, ReviewOutcome } from "./types.js";
|
|
9
11
|
export { Approval, Approvals, POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
|
|
10
12
|
export { Comments, Reports } from "./reports.js";
|
|
11
13
|
export { Review, Reviews, type ReviewWaitOptions } from "./reviews.js";
|
|
14
|
+
export { Collection, Collections, type CollectWaitOptions } from "./collections.js";
|
|
15
|
+
export { Flow, Flows, type FlowPrimitives } from "./flows.js";
|
|
12
16
|
export { constructEvent, DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER, TOLERANCE_SECONDS, verifySignature, Webhooks, } from "./webhooks.js";
|
|
13
17
|
export { DeliverdError, DeliverdTimeoutError } from "./errors.js";
|
|
14
18
|
export { DEFAULT_BASE_URL, type ClientOptions } from "./http.js";
|
|
@@ -66,6 +70,23 @@ export interface ReviewOptions extends Omit<CreateReviewInput, "expiresAt"> {
|
|
|
66
70
|
*/
|
|
67
71
|
reuse?: boolean;
|
|
68
72
|
}
|
|
73
|
+
/** Everything `collect()` takes, plus the conveniences it adds on top. */
|
|
74
|
+
export interface CollectOptions extends Omit<CreateCollectionInput, "expiresAt"> {
|
|
75
|
+
/** `"4h"`, `"30m"`, `"2d"`, or milliseconds. Default 24 hours. */
|
|
76
|
+
expiresIn?: Duration;
|
|
77
|
+
/** An exact moment instead, if you have one. */
|
|
78
|
+
expiresAt?: string;
|
|
79
|
+
/** Called after each poll — a progress line in a CLI. */
|
|
80
|
+
onPoll?: CollectWaitOptions["onPoll"];
|
|
81
|
+
/** Give up waiting after this. The request stays open until it expires. */
|
|
82
|
+
timeout?: Duration;
|
|
83
|
+
signal?: AbortSignal;
|
|
84
|
+
/**
|
|
85
|
+
* With an `externalId`, reuse an existing request rather than filing a
|
|
86
|
+
* second one, so a restarted agent does not ask the same people twice.
|
|
87
|
+
*/
|
|
88
|
+
reuse?: boolean;
|
|
89
|
+
}
|
|
69
90
|
/**
|
|
70
91
|
* Deliverd: you build the action, Deliverd handles the human.
|
|
71
92
|
*
|
|
@@ -88,6 +109,8 @@ export interface ReviewOptions extends Omit<CreateReviewInput, "expiresAt"> {
|
|
|
88
109
|
export declare class Deliverd {
|
|
89
110
|
readonly approvals: Approvals;
|
|
90
111
|
readonly reviews: Reviews;
|
|
112
|
+
readonly collections: Collections;
|
|
113
|
+
readonly flows: Flows;
|
|
91
114
|
readonly reports: Reports;
|
|
92
115
|
readonly comments: Comments;
|
|
93
116
|
readonly webhooks: Webhooks;
|
|
@@ -137,6 +160,29 @@ export declare class Deliverd {
|
|
|
137
160
|
* you say otherwise, so a wait always ends.
|
|
138
161
|
*/
|
|
139
162
|
review(options: ReviewOptions): Promise<ReviewOutcome>;
|
|
163
|
+
/**
|
|
164
|
+
* Ask people for what you do not have, and wait for it.
|
|
165
|
+
*
|
|
166
|
+
* `approve()` asks permission, `review()` asks judgement, and this asks for
|
|
167
|
+
* a fact — a figure, a date, a choice between options, the sentence only
|
|
168
|
+
* they can write.
|
|
169
|
+
*
|
|
170
|
+
* ```ts
|
|
171
|
+
* const { answers } = await deliverd.collect({
|
|
172
|
+
* title: "Before I file the Q3 return",
|
|
173
|
+
* respondents: ["finance@firm.example"],
|
|
174
|
+
* questions: [
|
|
175
|
+
* { prompt: "Headcount at 30 September", kind: "number" },
|
|
176
|
+
* { prompt: "Any disposals in the quarter?", kind: "boolean" },
|
|
177
|
+
* ],
|
|
178
|
+
* });
|
|
179
|
+
* ```
|
|
180
|
+
*
|
|
181
|
+
* `answers` is keyed by the question you asked. Check `complete` before you
|
|
182
|
+
* use it: a request that expired has whatever arrived and no more, and the
|
|
183
|
+
* thing you do without the figure is usually not the thing you do with it.
|
|
184
|
+
*/
|
|
185
|
+
collect(options: CollectOptions): Promise<CollectedAnswers>;
|
|
140
186
|
/** Publish HTML to a secure URL. The other half of the product, one call in. */
|
|
141
187
|
publish(input: PublishReportInput, signal?: AbortSignal): Promise<PublishResult>;
|
|
142
188
|
}
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAsB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EACL,cAAc,EACd,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC1D,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACvE,mBAAmB,YAAY,CAAC;AAEhC,+EAA+E;AAC/E,eAAO,MAAM,cAAc,EAAE,QAAgB,CAAC;AAE9C,MAAM,WAAW,eAAgB,SAAQ,OAAO,CAAC,aAAa,CAAC;IAC7D;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC;IAC5E,kEAAkE;IAClE,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IACvC,yDAAyD;IACzD,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC/B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,iBAAiB,EAAE,WAAW,CAAC;IACzE,kEAAkE;IAClE,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,MAAM,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACrC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAElB,OAAO,GAAE,eAAoB;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/index.js
CHANGED
|
@@ -2,12 +2,16 @@ import { HttpClient } from "./http.js";
|
|
|
2
2
|
import { Approvals, FAST_POLL_SCHEDULE } from "./approvals.js";
|
|
3
3
|
import { Comments, Reports } from "./reports.js";
|
|
4
4
|
import { Reviews } from "./reviews.js";
|
|
5
|
+
import { Collections } from "./collections.js";
|
|
6
|
+
import { Flows } from "./flows.js";
|
|
5
7
|
import { Webhooks } from "./webhooks.js";
|
|
6
8
|
import { developmentFetch } from "./dev.js";
|
|
7
9
|
import { durationMs } from "./duration.js";
|
|
8
10
|
export { Approval, Approvals, POLL_SCHEDULE } from "./approvals.js";
|
|
9
11
|
export { Comments, Reports } from "./reports.js";
|
|
10
12
|
export { Review, Reviews } from "./reviews.js";
|
|
13
|
+
export { Collection, Collections } from "./collections.js";
|
|
14
|
+
export { Flow, Flows } from "./flows.js";
|
|
11
15
|
export { constructEvent, DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER, TOLERANCE_SECONDS, verifySignature, Webhooks, } from "./webhooks.js";
|
|
12
16
|
export { DeliverdError, DeliverdTimeoutError } from "./errors.js";
|
|
13
17
|
export { DEFAULT_BASE_URL } from "./http.js";
|
|
@@ -36,6 +40,8 @@ export const DEFAULT_EXPIRY = "24h";
|
|
|
36
40
|
export class Deliverd {
|
|
37
41
|
approvals;
|
|
38
42
|
reviews;
|
|
43
|
+
collections;
|
|
44
|
+
flows;
|
|
39
45
|
reports;
|
|
40
46
|
comments;
|
|
41
47
|
webhooks;
|
|
@@ -54,6 +60,13 @@ export class Deliverd {
|
|
|
54
60
|
});
|
|
55
61
|
this.approvals = new Approvals(this.http);
|
|
56
62
|
this.reviews = new Reviews(this.http);
|
|
63
|
+
this.collections = new Collections(this.http);
|
|
64
|
+
/*
|
|
65
|
+
* The handle takes the client so `flow.approve()` is the same call as
|
|
66
|
+
* `deliverd.approve()` with the flow filled in, rather than a second
|
|
67
|
+
* implementation that can drift from it.
|
|
68
|
+
*/
|
|
69
|
+
this.flows = new Flows(this.http, this);
|
|
57
70
|
this.reports = new Reports(this.http);
|
|
58
71
|
this.comments = new Comments(this.http);
|
|
59
72
|
this.webhooks = new Webhooks();
|
|
@@ -166,6 +179,55 @@ export class Deliverd {
|
|
|
166
179
|
});
|
|
167
180
|
return settled.toOutcome();
|
|
168
181
|
}
|
|
182
|
+
/**
|
|
183
|
+
* Ask people for what you do not have, and wait for it.
|
|
184
|
+
*
|
|
185
|
+
* `approve()` asks permission, `review()` asks judgement, and this asks for
|
|
186
|
+
* a fact — a figure, a date, a choice between options, the sentence only
|
|
187
|
+
* they can write.
|
|
188
|
+
*
|
|
189
|
+
* ```ts
|
|
190
|
+
* const { answers } = await deliverd.collect({
|
|
191
|
+
* title: "Before I file the Q3 return",
|
|
192
|
+
* respondents: ["finance@firm.example"],
|
|
193
|
+
* questions: [
|
|
194
|
+
* { prompt: "Headcount at 30 September", kind: "number" },
|
|
195
|
+
* { prompt: "Any disposals in the quarter?", kind: "boolean" },
|
|
196
|
+
* ],
|
|
197
|
+
* });
|
|
198
|
+
* ```
|
|
199
|
+
*
|
|
200
|
+
* `answers` is keyed by the question you asked. Check `complete` before you
|
|
201
|
+
* use it: a request that expired has whatever arrived and no more, and the
|
|
202
|
+
* thing you do without the figure is usually not the thing you do with it.
|
|
203
|
+
*/
|
|
204
|
+
async collect(options) {
|
|
205
|
+
const { expiresIn, timeout, onPoll, signal, reuse, ...input } = options;
|
|
206
|
+
if (input.externalId && reuse !== false) {
|
|
207
|
+
const existing = await this.collections.findByExternalId(input.externalId, signal);
|
|
208
|
+
if (existing) {
|
|
209
|
+
const settled = await existing.wait({
|
|
210
|
+
onPoll,
|
|
211
|
+
signal,
|
|
212
|
+
timeout: durationOrUndefined(timeout),
|
|
213
|
+
...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
|
|
214
|
+
});
|
|
215
|
+
return settled.toCollected();
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
const collection = await this.collections.create({
|
|
219
|
+
...input,
|
|
220
|
+
expiresAt: options.expiresAt ??
|
|
221
|
+
new Date(Date.now() + durationMs(expiresIn ?? DEFAULT_EXPIRY)).toISOString(),
|
|
222
|
+
}, signal);
|
|
223
|
+
const settled = await collection.wait({
|
|
224
|
+
onPoll,
|
|
225
|
+
signal,
|
|
226
|
+
timeout: durationOrUndefined(timeout) ?? (this.development ? 2_000 : undefined),
|
|
227
|
+
...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
|
|
228
|
+
});
|
|
229
|
+
return settled.toCollected();
|
|
230
|
+
}
|
|
169
231
|
/** Publish HTML to a secure URL. The other half of the product, one call in. */
|
|
170
232
|
publish(input, signal) {
|
|
171
233
|
return this.reports.publish(input, signal);
|
package/dist/types.d.ts
CHANGED
|
@@ -72,6 +72,12 @@ export interface CreateApprovalInput {
|
|
|
72
72
|
expiresAt?: string;
|
|
73
73
|
/** Your own reference, returned unchanged and searchable. */
|
|
74
74
|
externalId?: string;
|
|
75
|
+
/**
|
|
76
|
+
* The flow this belongs to, when it is one step of a larger piece of work.
|
|
77
|
+
* Must be an open flow in your organisation. `flow.approve()` and its
|
|
78
|
+
* siblings set this for you.
|
|
79
|
+
*/
|
|
80
|
+
flowId?: string;
|
|
75
81
|
metadata?: Record<string, unknown>;
|
|
76
82
|
}
|
|
77
83
|
/**
|
|
@@ -168,7 +174,7 @@ export interface CommentThread {
|
|
|
168
174
|
}[];
|
|
169
175
|
[key: string]: unknown;
|
|
170
176
|
}
|
|
171
|
-
export type WebhookEventName = "report.published" | "report.updated" | "report.shared" | "report.viewed" | "comment.created" | "access.requested" | "schedule.due" | "publish.held" | "approval.requested" | "approval.approved" | "approval.rejected" | "approval.expired" | "approval.question" | "approval.answered" | "review.requested" | "review.approved" | "review.changes_requested";
|
|
177
|
+
export type WebhookEventName = "report.published" | "report.updated" | "report.shared" | "report.viewed" | "comment.created" | "access.requested" | "schedule.due" | "publish.held" | "approval.requested" | "approval.approved" | "approval.rejected" | "approval.expired" | "approval.question" | "approval.answered" | "review.requested" | "review.approved" | "review.changes_requested" | "collection.requested" | "collection.completed" | "flow.completed";
|
|
172
178
|
export interface WebhookEvent {
|
|
173
179
|
event: WebhookEventName;
|
|
174
180
|
sentAt: string;
|
|
@@ -204,6 +210,12 @@ export interface CreateReviewInput {
|
|
|
204
210
|
expiresAt?: string;
|
|
205
211
|
/** Your own reference, returned unchanged and searchable. */
|
|
206
212
|
externalId?: string;
|
|
213
|
+
/**
|
|
214
|
+
* The flow this belongs to, when it is one step of a larger piece of work.
|
|
215
|
+
* Must be an open flow in your organisation. `flow.approve()` and its
|
|
216
|
+
* siblings set this for you.
|
|
217
|
+
*/
|
|
218
|
+
flowId?: string;
|
|
207
219
|
metadata?: Record<string, unknown>;
|
|
208
220
|
}
|
|
209
221
|
export interface ReviewerRef {
|
|
@@ -258,4 +270,165 @@ export interface ListReviewsInput {
|
|
|
258
270
|
reportId?: string;
|
|
259
271
|
limit?: number;
|
|
260
272
|
}
|
|
273
|
+
export type CollectionStatus = "pending" | "complete" | "expired" | "cancelled";
|
|
274
|
+
export type QuestionKind = "text" | "long_text" | "number" | "date" | "choice" | "multi_choice" | "boolean";
|
|
275
|
+
/** What an answer can hold, shaped by its question's kind. */
|
|
276
|
+
export type AnswerValue = string | number | boolean | string[];
|
|
277
|
+
export interface QuestionInput {
|
|
278
|
+
/** The question, as you would ask it out loud. */
|
|
279
|
+
prompt: string;
|
|
280
|
+
/** The sentence under the field that stops the wrong answer being given. */
|
|
281
|
+
help?: string;
|
|
282
|
+
kind: QuestionKind;
|
|
283
|
+
/** Required unless you say otherwise; a required question blocks submission. */
|
|
284
|
+
required?: boolean;
|
|
285
|
+
/** For `choice` and `multi_choice`. At least two, or it is not a question. */
|
|
286
|
+
options?: string[];
|
|
287
|
+
}
|
|
288
|
+
export interface CreateCollectionInput {
|
|
289
|
+
/** What you need, as a headline the person sees first. */
|
|
290
|
+
title: string;
|
|
291
|
+
/** Why you are asking, shown above the questions. */
|
|
292
|
+
instructions?: string;
|
|
293
|
+
questions: QuestionInput[];
|
|
294
|
+
/**
|
|
295
|
+
* Emails or user ids. An active member, or a guest the organisation already
|
|
296
|
+
* knows — anyone else is refused rather than emailed.
|
|
297
|
+
*/
|
|
298
|
+
respondents: string[];
|
|
299
|
+
/** How many submitted replies complete it; everyone asked, when omitted. */
|
|
300
|
+
requiredResponses?: number;
|
|
301
|
+
/** A published report the request is about. */
|
|
302
|
+
reportId?: string;
|
|
303
|
+
/** Shown to the person, and what the single reminder is measured against. */
|
|
304
|
+
dueAt?: string;
|
|
305
|
+
/** After this the request closes unanswered. ISO 8601. */
|
|
306
|
+
expiresAt?: string;
|
|
307
|
+
externalId?: string;
|
|
308
|
+
/**
|
|
309
|
+
* The flow this belongs to, when it is one step of a larger piece of work.
|
|
310
|
+
* Must be an open flow in your organisation. `flow.approve()` and its
|
|
311
|
+
* siblings set this for you.
|
|
312
|
+
*/
|
|
313
|
+
flowId?: string;
|
|
314
|
+
metadata?: Record<string, unknown>;
|
|
315
|
+
}
|
|
316
|
+
export interface CollectionQuestion {
|
|
317
|
+
id: string;
|
|
318
|
+
prompt: string;
|
|
319
|
+
help: string | null;
|
|
320
|
+
kind: QuestionKind;
|
|
321
|
+
required: boolean;
|
|
322
|
+
options: string[];
|
|
323
|
+
}
|
|
324
|
+
export interface CollectionReply {
|
|
325
|
+
/** Who answered, as a name rather than an id. */
|
|
326
|
+
respondent: string;
|
|
327
|
+
status: "pending" | "submitted";
|
|
328
|
+
submittedAt: string | null;
|
|
329
|
+
/** Empty until they submit: a half-typed draft is not what they meant to say. */
|
|
330
|
+
answers: {
|
|
331
|
+
question: string;
|
|
332
|
+
kind: QuestionKind;
|
|
333
|
+
value: AnswerValue;
|
|
334
|
+
}[];
|
|
335
|
+
}
|
|
336
|
+
export interface CollectionData {
|
|
337
|
+
id: string;
|
|
338
|
+
status: CollectionStatus;
|
|
339
|
+
/** The page the person fills in. */
|
|
340
|
+
url: string;
|
|
341
|
+
title: string;
|
|
342
|
+
instructions: string | null;
|
|
343
|
+
reportId: string | null;
|
|
344
|
+
externalId: string | null;
|
|
345
|
+
metadata: Record<string, unknown>;
|
|
346
|
+
requestedBy: string;
|
|
347
|
+
requiredResponses: number;
|
|
348
|
+
questions: CollectionQuestion[];
|
|
349
|
+
responses: CollectionReply[];
|
|
350
|
+
submittedCount: number;
|
|
351
|
+
askedCount: number;
|
|
352
|
+
settledAt: string | null;
|
|
353
|
+
dueAt: string | null;
|
|
354
|
+
expiresAt: string | null;
|
|
355
|
+
createdAt: string;
|
|
356
|
+
}
|
|
357
|
+
/** The answers, flattened — what `collect()` hands back. */
|
|
358
|
+
export interface CollectedAnswers {
|
|
359
|
+
/** True when enough people replied; false if it expired or was withdrawn. */
|
|
360
|
+
complete: boolean;
|
|
361
|
+
status: Exclude<CollectionStatus, "pending">;
|
|
362
|
+
/** Every submitted reply, in the order they arrived. */
|
|
363
|
+
responses: CollectionReply[];
|
|
364
|
+
/**
|
|
365
|
+
* The first submitted answer to each question, by its prompt — the shape
|
|
366
|
+
* most callers want when they asked one person for three facts.
|
|
367
|
+
*/
|
|
368
|
+
answers: Record<string, AnswerValue>;
|
|
369
|
+
id: string;
|
|
370
|
+
url: string;
|
|
371
|
+
collection: CollectionData;
|
|
372
|
+
}
|
|
373
|
+
export interface ListCollectionsInput {
|
|
374
|
+
status?: CollectionStatus;
|
|
375
|
+
externalId?: string;
|
|
376
|
+
limit?: number;
|
|
377
|
+
}
|
|
378
|
+
export type FlowStatus = "open" | "complete" | "cancelled";
|
|
379
|
+
export type FlowMemberKind = "approval" | "review" | "collection" | "report";
|
|
380
|
+
export interface FlowMember {
|
|
381
|
+
kind: FlowMemberKind;
|
|
382
|
+
id: string;
|
|
383
|
+
title: string;
|
|
384
|
+
/** The member's own status word, which differs by kind. */
|
|
385
|
+
status: string;
|
|
386
|
+
/** Still waiting on somebody. Always false for a report. */
|
|
387
|
+
open: boolean;
|
|
388
|
+
createdAt: string;
|
|
389
|
+
}
|
|
390
|
+
/** One line of the history: what happened, who did it, when. */
|
|
391
|
+
export interface FlowEvent {
|
|
392
|
+
event: string;
|
|
393
|
+
actor: string;
|
|
394
|
+
actorType: string;
|
|
395
|
+
resourceType: string | null;
|
|
396
|
+
resourceId: string | null;
|
|
397
|
+
at: string;
|
|
398
|
+
}
|
|
399
|
+
export interface FlowData {
|
|
400
|
+
id: string;
|
|
401
|
+
status: FlowStatus;
|
|
402
|
+
/** The timeline page a person can open. */
|
|
403
|
+
url: string;
|
|
404
|
+
title: string;
|
|
405
|
+
description: string | null;
|
|
406
|
+
externalId: string | null;
|
|
407
|
+
metadata: Record<string, unknown>;
|
|
408
|
+
startedBy: string;
|
|
409
|
+
members: FlowMember[];
|
|
410
|
+
memberCount: number;
|
|
411
|
+
openCount: number;
|
|
412
|
+
/** Nothing outstanding right now — not a claim that the job is finished. */
|
|
413
|
+
allSettled: boolean;
|
|
414
|
+
/** Present on a single read, absent from a list. */
|
|
415
|
+
timeline?: FlowEvent[];
|
|
416
|
+
settledAt: string | null;
|
|
417
|
+
createdAt: string;
|
|
418
|
+
}
|
|
419
|
+
export interface CreateFlowInput {
|
|
420
|
+
/** What this piece of work is, as the timeline will be titled. */
|
|
421
|
+
title: string;
|
|
422
|
+
/** What it is for, for whoever reads the history a year from now. */
|
|
423
|
+
description?: string;
|
|
424
|
+
workspaceId?: string;
|
|
425
|
+
/** Your own reference. Pass it and use `resume()` so a restart does not start a second flow. */
|
|
426
|
+
externalId?: string;
|
|
427
|
+
metadata?: Record<string, unknown>;
|
|
428
|
+
}
|
|
429
|
+
export interface ListFlowsInput {
|
|
430
|
+
status?: FlowStatus;
|
|
431
|
+
externalId?: string;
|
|
432
|
+
limit?: number;
|
|
433
|
+
}
|
|
261
434
|
//# sourceMappingURL=types.d.ts.map
|