@deliverd/sdk 0.6.1 → 0.7.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 +67 -2
- package/dist/approvals.d.ts +12 -0
- package/dist/approvals.d.ts.map +1 -1
- package/dist/approvals.js +33 -4
- package/dist/collections.d.ts +10 -0
- package/dist/collections.d.ts.map +1 -1
- package/dist/collections.js +18 -3
- package/dist/dev.d.ts.map +1 -1
- package/dist/dev.js +16 -3
- package/dist/flows.d.ts +10 -0
- package/dist/flows.d.ts.map +1 -1
- package/dist/flows.js +18 -3
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -2
- package/dist/messages.d.ts.map +1 -1
- package/dist/messages.js +8 -4
- package/dist/paging.d.ts +43 -0
- package/dist/paging.d.ts.map +1 -0
- package/dist/paging.js +27 -0
- package/dist/released.d.ts +29 -0
- package/dist/released.d.ts.map +1 -0
- package/dist/released.js +402 -0
- package/dist/reports.d.ts +152 -4
- package/dist/reports.d.ts.map +1 -1
- package/dist/reports.js +209 -10
- package/dist/reviews.d.ts +10 -0
- package/dist/reviews.d.ts.map +1 -1
- package/dist/reviews.js +18 -8
- package/dist/types.d.ts +147 -3
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/approvals.ts +40 -4
- package/src/collections.ts +25 -3
- package/src/dev.ts +16 -3
- package/src/flows.ts +25 -3
- package/src/index.ts +4 -2
- package/src/messages.ts +8 -4
- package/src/paging.ts +64 -0
- package/src/released.ts +403 -0
- package/src/reports.ts +268 -12
- package/src/reviews.ts +25 -8
- package/src/types.ts +155 -3
package/src/approvals.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { listOrCollect, type PageOf } from "./paging.js";
|
|
1
2
|
import { DeliverdError, DeliverdTimeoutError } from "./errors.js";
|
|
2
3
|
import type { HttpClient } from "./http.js";
|
|
3
4
|
import { durationMs, type Duration } from "./duration.js";
|
|
@@ -87,7 +88,9 @@ export class Approval {
|
|
|
87
88
|
get title(): string { return this.data.title; }
|
|
88
89
|
/** Their reason, when they gave one. */
|
|
89
90
|
get note(): string | null { return this.data.note; }
|
|
91
|
+
/** Who decided, as a name rather than an id. */
|
|
90
92
|
get decidedBy(): string | null { return this.data.decidedBy; }
|
|
93
|
+
get decidedById(): string | null { return this.data.decidedById; }
|
|
91
94
|
get decidedAt(): string | null { return this.data.decidedAt; }
|
|
92
95
|
get questions(): ApprovalQuestion[] { return this.data.questions; }
|
|
93
96
|
/** Questions the approver is still waiting on you to answer. */
|
|
@@ -117,6 +120,7 @@ export class Approval {
|
|
|
117
120
|
status,
|
|
118
121
|
note: this.data.note,
|
|
119
122
|
decidedBy: this.data.decidedBy,
|
|
123
|
+
decidedById: this.data.decidedById,
|
|
120
124
|
decidedAt: this.data.decidedAt,
|
|
121
125
|
id: this.data.id,
|
|
122
126
|
url: this.data.url,
|
|
@@ -176,8 +180,19 @@ export class Approval {
|
|
|
176
180
|
});
|
|
177
181
|
}
|
|
178
182
|
if (deadline !== undefined && Date.now() >= deadline) {
|
|
183
|
+
/*
|
|
184
|
+
* Say which of the two happened. An approver who asked a question and
|
|
185
|
+
* got no answer has not ignored the request — they are waiting on you,
|
|
186
|
+
* and "nobody decided in time" sends you to look at the wrong end of
|
|
187
|
+
* it. Found by running the quickstart's own instruction to set
|
|
188
|
+
* DELIVERD_DEV_OUTCOME=question, which produced exactly that message.
|
|
189
|
+
*/
|
|
190
|
+
const unanswered = this.data.questions?.find((q) => !q.answer);
|
|
179
191
|
throw new DeliverdTimeoutError(
|
|
180
|
-
|
|
192
|
+
unanswered
|
|
193
|
+
? `An approver asked a question about "${this.data.title}" and nothing answered it: ` +
|
|
194
|
+
`"${unanswered.question}". Pass an onQuestion handler, or answer it at ${this.data.url}.`
|
|
195
|
+
: `Nobody decided "${this.data.title}" within the timeout. It is still open at ${this.data.url}.`
|
|
181
196
|
);
|
|
182
197
|
}
|
|
183
198
|
|
|
@@ -246,14 +261,35 @@ export class Approvals {
|
|
|
246
261
|
return new Approval(this.http, data);
|
|
247
262
|
}
|
|
248
263
|
|
|
264
|
+
/**
|
|
265
|
+
* The organisation's approvals, newest first.
|
|
266
|
+
*
|
|
267
|
+
* With no `limit` this is every one of them: the API says where each page
|
|
268
|
+
* stopped and this follows the cursor to the end. With a `limit` it is one
|
|
269
|
+
* page of that size, and `listPage` hands back the cursor to continue from.
|
|
270
|
+
*/
|
|
249
271
|
async list(input: ListApprovalsInput = {}, signal?: AbortSignal): Promise<Approval[]> {
|
|
250
|
-
|
|
272
|
+
return listOrCollect(input, async (q: { limit?: number; cursor?: string }) => {
|
|
273
|
+
const page = await this.listPage({ ...input, ...q }, signal);
|
|
274
|
+
return { items: page.items, nextCursor: page.nextCursor };
|
|
275
|
+
});
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** One page, and the cursor to continue from — null when it is the end. */
|
|
279
|
+
async listPage(
|
|
280
|
+
input: ListApprovalsInput = {},
|
|
281
|
+
signal?: AbortSignal
|
|
282
|
+
): Promise<PageOf<Approval>> {
|
|
283
|
+
const { approvals, nextCursor } = await this.http.request<{
|
|
284
|
+
approvals: ApprovalData[];
|
|
285
|
+
nextCursor: string | null;
|
|
286
|
+
}>({
|
|
251
287
|
method: "GET",
|
|
252
288
|
path: "/approvals",
|
|
253
|
-
query: { status: input.status, externalId: input.externalId, limit: input.limit },
|
|
289
|
+
query: { status: input.status, externalId: input.externalId, limit: input.limit, cursor: input.cursor },
|
|
254
290
|
signal,
|
|
255
291
|
});
|
|
256
|
-
return approvals.map((
|
|
292
|
+
return { items: approvals.map((r) => new Approval(this.http, r)), nextCursor };
|
|
257
293
|
}
|
|
258
294
|
|
|
259
295
|
/**
|
package/src/collections.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { listOrCollect, type PageOf } from "./paging.js";
|
|
1
2
|
import { DeliverdError, DeliverdTimeoutError } from "./errors.js";
|
|
2
3
|
import type { HttpClient } from "./http.js";
|
|
3
4
|
import { POLL_SCHEDULE } from "./approvals.js";
|
|
@@ -187,14 +188,35 @@ export class Collections {
|
|
|
187
188
|
return new Collection(this.http, data);
|
|
188
189
|
}
|
|
189
190
|
|
|
191
|
+
/**
|
|
192
|
+
* The organisation's collections, newest first.
|
|
193
|
+
*
|
|
194
|
+
* With no `limit` this is every one of them: the API says where each page
|
|
195
|
+
* stopped and this follows the cursor to the end. With a `limit` it is one
|
|
196
|
+
* page of that size, and `listPage` hands back the cursor to continue from.
|
|
197
|
+
*/
|
|
190
198
|
async list(input: ListCollectionsInput = {}, signal?: AbortSignal): Promise<Collection[]> {
|
|
191
|
-
|
|
199
|
+
return listOrCollect(input, async (q: { limit?: number; cursor?: string }) => {
|
|
200
|
+
const page = await this.listPage({ ...input, ...q }, signal);
|
|
201
|
+
return { items: page.items, nextCursor: page.nextCursor };
|
|
202
|
+
});
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/** One page, and the cursor to continue from — null when it is the end. */
|
|
206
|
+
async listPage(
|
|
207
|
+
input: ListCollectionsInput = {},
|
|
208
|
+
signal?: AbortSignal
|
|
209
|
+
): Promise<PageOf<Collection>> {
|
|
210
|
+
const { collections, nextCursor } = await this.http.request<{
|
|
211
|
+
collections: CollectionData[];
|
|
212
|
+
nextCursor: string | null;
|
|
213
|
+
}>({
|
|
192
214
|
method: "GET",
|
|
193
215
|
path: "/collections",
|
|
194
|
-
query: { status: input.status, externalId: input.externalId, limit: input.limit },
|
|
216
|
+
query: { status: input.status, externalId: input.externalId, limit: input.limit, cursor: input.cursor },
|
|
195
217
|
signal,
|
|
196
218
|
});
|
|
197
|
-
return collections.map((
|
|
219
|
+
return { items: collections.map((r) => new Collection(this.http, r)), nextCursor };
|
|
198
220
|
}
|
|
199
221
|
|
|
200
222
|
/** Ask and wait, for the common case where there is nothing to do between. */
|
package/src/dev.ts
CHANGED
|
@@ -108,6 +108,7 @@ export function developmentFetch(options: DevelopmentOptions = {}): typeof globa
|
|
|
108
108
|
requiredApprovals: 1,
|
|
109
109
|
approvalsSoFar: 0,
|
|
110
110
|
decidedBy: null,
|
|
111
|
+
decidedById: null,
|
|
111
112
|
decidedAt: null,
|
|
112
113
|
note: null,
|
|
113
114
|
expiresAt: (body.expiresAt as string | undefined) ?? null,
|
|
@@ -193,7 +194,13 @@ export function developmentFetch(options: DevelopmentOptions = {}): typeof globa
|
|
|
193
194
|
requiredApprovals: (body.requiredApprovals as number | undefined) ?? 1,
|
|
194
195
|
reviewers,
|
|
195
196
|
verdicts: [],
|
|
196
|
-
|
|
197
|
+
/*
|
|
198
|
+
* A review that asks for changes has something to read, and the count
|
|
199
|
+
* is what the caller acts on. Zero made the one path that matters read
|
|
200
|
+
* as "changes requested — 0 threads", which tells somebody running
|
|
201
|
+
* this for the first time that the feature does not work.
|
|
202
|
+
*/
|
|
203
|
+
threadCount: verdict === "changes_requested" ? 2 : 0,
|
|
197
204
|
settledAt: null,
|
|
198
205
|
expiresAt: (body.expiresAt as string | undefined) ?? null,
|
|
199
206
|
createdAt: new Date().toISOString(),
|
|
@@ -381,7 +388,7 @@ export function developmentFetch(options: DevelopmentOptions = {}): typeof globa
|
|
|
381
388
|
const title = kind === "flow" ? (flowStore.get(id)?.title ?? "A flow") : "A report";
|
|
382
389
|
const now = new Date().toISOString();
|
|
383
390
|
const pack: EvidencePack = {
|
|
384
|
-
packVersion:
|
|
391
|
+
packVersion: 2,
|
|
385
392
|
generatedAt: now,
|
|
386
393
|
generatedBy: "You (development mode)",
|
|
387
394
|
organisation: { id: "org_dev", name: "Development" },
|
|
@@ -465,7 +472,13 @@ function settle(stored: Stored): void {
|
|
|
465
472
|
if (stored.outcome === "question" && stored.data.questions.some((q) => !q.answer)) return;
|
|
466
473
|
|
|
467
474
|
stored.data.status = stored.outcome === "rejected" ? "rejected" : "approved";
|
|
468
|
-
|
|
475
|
+
/*
|
|
476
|
+
* The same shape production sends: a person's name in `decidedBy` and the
|
|
477
|
+
* key in `decidedById`. It used to be an email-shaped string alone, so the
|
|
478
|
+
* offline loop taught a shape a real organisation never delivers.
|
|
479
|
+
*/
|
|
480
|
+
stored.data.decidedBy = "Development approver";
|
|
481
|
+
stored.data.decidedById = "00000000-0000-0000-0000-00000000dev0";
|
|
469
482
|
stored.data.decidedAt = new Date().toISOString();
|
|
470
483
|
stored.data.note =
|
|
471
484
|
stored.options.note ??
|
package/src/flows.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { listOrCollect, type PageOf } from "./paging.js";
|
|
1
2
|
import type { HttpClient } from "./http.js";
|
|
2
3
|
import type { CreateFlowInput, EvidencePack, FlowData, ListFlowsInput } from "./types.js";
|
|
3
4
|
/*
|
|
@@ -168,14 +169,35 @@ export class Flows {
|
|
|
168
169
|
return new Flow(this.http, data, this.client);
|
|
169
170
|
}
|
|
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
|
+
*/
|
|
171
179
|
async list(input: ListFlowsInput = {}, signal?: AbortSignal): Promise<Flow[]> {
|
|
172
|
-
|
|
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
|
+
}>({
|
|
173
195
|
method: "GET",
|
|
174
196
|
path: "/flows",
|
|
175
|
-
query: { status: input.status, externalId: input.externalId, limit: input.limit },
|
|
197
|
+
query: { status: input.status, externalId: input.externalId, limit: input.limit, cursor: input.cursor },
|
|
176
198
|
signal,
|
|
177
199
|
});
|
|
178
|
-
return flows.map((f) => new Flow(this.http, f, this.client));
|
|
200
|
+
return { items: flows.map((f) => new Flow(this.http, f, this.client)), nextCursor };
|
|
179
201
|
}
|
|
180
202
|
|
|
181
203
|
/** The same job as before, when there was one — so a restart extends it rather than starting a second. */
|
package/src/index.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { HttpClient, type ClientOptions } from "./http.js";
|
|
2
2
|
import { Approvals, FAST_POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
|
|
3
|
-
import { Comments, Reports } from "./reports.js";
|
|
3
|
+
import { Comments, Reports, Schedules } from "./reports.js";
|
|
4
4
|
import { Reviews, type ReviewWaitOptions } from "./reviews.js";
|
|
5
5
|
import { Collections, type CollectWaitOptions } from "./collections.js";
|
|
6
6
|
import { Flows } from "./flows.js";
|
|
@@ -20,7 +20,7 @@ import type {
|
|
|
20
20
|
} from "./types.js";
|
|
21
21
|
|
|
22
22
|
export { Approval, Approvals, POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
|
|
23
|
-
export { Comments, Reports } from "./reports.js";
|
|
23
|
+
export { Comments, Reports, Schedules } from "./reports.js";
|
|
24
24
|
export { Review, Reviews, type ReviewWaitOptions } from "./reviews.js";
|
|
25
25
|
export { Collection, Collections, type CollectWaitOptions } from "./collections.js";
|
|
26
26
|
export { Flow, Flows, type FlowPrimitives } from "./flows.js";
|
|
@@ -138,6 +138,7 @@ export class Deliverd {
|
|
|
138
138
|
readonly flows: Flows;
|
|
139
139
|
readonly reports: Reports;
|
|
140
140
|
readonly comments: Comments;
|
|
141
|
+
readonly schedules: Schedules;
|
|
141
142
|
readonly webhooks: Webhooks;
|
|
142
143
|
readonly http: HttpClient;
|
|
143
144
|
/** Whether an imaginary approver is deciding these. */
|
|
@@ -166,6 +167,7 @@ export class Deliverd {
|
|
|
166
167
|
this.flows = new Flows(this.http, this);
|
|
167
168
|
this.reports = new Reports(this.http);
|
|
168
169
|
this.comments = new Comments(this.http);
|
|
170
|
+
this.schedules = new Schedules(this.http);
|
|
169
171
|
this.webhooks = new Webhooks();
|
|
170
172
|
}
|
|
171
173
|
|
package/src/messages.ts
CHANGED
|
@@ -23,11 +23,15 @@ export const EXPLANATIONS: Record<string, Explanation> = {
|
|
|
23
23
|
hint: "Set DELIVERD_API_KEY in your environment, or pass { apiKey } — or use { mode: \"development\" } to run without one.",
|
|
24
24
|
},
|
|
25
25
|
auth_error: {
|
|
26
|
-
message: "That
|
|
27
|
-
|
|
26
|
+
message: "That credential was not accepted.",
|
|
27
|
+
// Both families, because both work: a `dlv_` key somebody created, or a
|
|
28
|
+
// `dlvo_` access token from an OAuth connector. Naming only the first is
|
|
29
|
+
// how a connector's token gets thrown away and replaced with a key
|
|
30
|
+
// nobody needed to create.
|
|
31
|
+
hint: "Check DELIVERD_API_KEY. An API key starts with dlv_ and is created in Settings → API tokens; an OAuth access token starts with dlvo_ and needs no setup.",
|
|
28
32
|
},
|
|
29
33
|
insufficient_scope: {
|
|
30
|
-
hint: "Reissue the key with the scope named above. A
|
|
34
|
+
hint: "Reissue the key with the scope named above, or re-consent the connector for it. A credential issued before a scope existed does not have it.",
|
|
31
35
|
},
|
|
32
36
|
unknown_approver: {
|
|
33
37
|
message: "No approver could be found for this request.",
|
|
@@ -63,7 +67,7 @@ export const EXPLANATIONS: Record<string, Explanation> = {
|
|
|
63
67
|
hint: "Check the machine's network and `baseUrl`. Deliverd's status is at https://deliverd.dev.",
|
|
64
68
|
},
|
|
65
69
|
timeout: {
|
|
66
|
-
hint: "
|
|
70
|
+
hint: "You stopped waiting; the request is still open at the URL above until it expires. If an approver asked a question, answer it with an `onQuestion` handler — an unanswered question is the commonest reason a wait runs out.",
|
|
67
71
|
},
|
|
68
72
|
invalid_signature: {
|
|
69
73
|
hint: "Check the endpoint's signing secret, and that you passed the raw request body rather than a re-encoded object.",
|
package/src/paging.ts
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import type { HttpClient } from "./http.js";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* What the SDK does about a list that does not fit in one answer.
|
|
5
|
+
*
|
|
6
|
+
* The API says where it stopped: a response carries `nextCursor`, null when
|
|
7
|
+
* the page is the end of the list and a string to pass back when it is not.
|
|
8
|
+
* That leaves the client one decision, and it is worth stating rather than
|
|
9
|
+
* leaving to whoever reads the call:
|
|
10
|
+
*
|
|
11
|
+
* **`limit` set means one page of that size. `limit` unset means all of
|
|
12
|
+
* them.** `list()` with no limit follows the cursor until the API stops
|
|
13
|
+
* offering one, so `.length` is the real count rather than a page size that
|
|
14
|
+
* happens to look like one. A caller who wants to page by hand asks for a
|
|
15
|
+
* `limit`, or uses `listPage` and drives the cursor themselves.
|
|
16
|
+
*
|
|
17
|
+
* The alternative — return a page and let the caller notice — reads fine and
|
|
18
|
+
* fails quietly, because a full page and a complete list are indistinguishable
|
|
19
|
+
* until somebody counts.
|
|
20
|
+
*/
|
|
21
|
+
export interface PageInput {
|
|
22
|
+
limit?: number;
|
|
23
|
+
cursor?: string;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export interface PageOf<T> {
|
|
27
|
+
items: T[];
|
|
28
|
+
nextCursor: string | null;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Follow the cursor to the end, collecting as we go.
|
|
33
|
+
*
|
|
34
|
+
* `fetchPage` is whatever single request the caller's endpoint makes; this
|
|
35
|
+
* only decides when to ask again. A page that comes back empty while still
|
|
36
|
+
* offering a cursor ends the loop as well — a server that did that would
|
|
37
|
+
* otherwise spin here for ever.
|
|
38
|
+
*/
|
|
39
|
+
export async function collect<T>(
|
|
40
|
+
fetchPage: (cursor: string | null) => Promise<PageOf<T>>
|
|
41
|
+
): Promise<T[]> {
|
|
42
|
+
const all: T[] = [];
|
|
43
|
+
let cursor: string | null = null;
|
|
44
|
+
for (;;) {
|
|
45
|
+
const page: PageOf<T> = await fetchPage(cursor);
|
|
46
|
+
all.push(...page.items);
|
|
47
|
+
if (!page.nextCursor || page.items.length === 0) return all;
|
|
48
|
+
cursor = page.nextCursor;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** One page, or every page, depending on whether a limit was asked for. */
|
|
53
|
+
export async function listOrCollect<T>(
|
|
54
|
+
input: PageInput,
|
|
55
|
+
fetchPage: (query: { limit?: number; cursor?: string }) => Promise<PageOf<T>>
|
|
56
|
+
): Promise<T[]> {
|
|
57
|
+
if (input.limit !== undefined) {
|
|
58
|
+
const page = await fetchPage({ limit: input.limit, cursor: input.cursor });
|
|
59
|
+
return page.items;
|
|
60
|
+
}
|
|
61
|
+
return collect((cursor) => fetchPage({ cursor: cursor ?? undefined }));
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export type { HttpClient };
|