@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/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
- `Nobody decided "${this.data.title}" within the timeout. It is still open at ${this.data.url}.`
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
- const { approvals } = await this.http.request<{ approvals: ApprovalData[] }>({
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((a) => new Approval(this.http, a));
292
+ return { items: approvals.map((r) => new Approval(this.http, r)), nextCursor };
257
293
  }
258
294
 
259
295
  /**
@@ -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
- const { collections } = await this.http.request<{ collections: CollectionData[] }>({
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((c) => new Collection(this.http, c));
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
- threadCount: 0,
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: 1,
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
- stored.data.decidedBy = "approver@development.invalid";
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
- const { flows } = await this.http.request<{ flows: FlowData[] }>({
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 API key was not accepted.",
27
- hint: "Check DELIVERD_API_KEY. Keys start with dlv_ and are created in Settings → API tokens.",
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 key issued before a scope existed does not have it.",
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: "Nobody decided in time. The request is still open at the URL above until it expires.",
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 };