@deliverd/sdk 0.2.0 → 0.3.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/index.ts CHANGED
@@ -2,12 +2,15 @@ import { HttpClient, type ClientOptions } from "./http.js";
2
2
  import { Approvals, FAST_POLL_SCHEDULE, 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";
5
6
  import { Webhooks } from "./webhooks.js";
6
7
  import { developmentFetch, type DevelopmentOptions } from "./dev.js";
7
8
  import { durationMs, type Duration } from "./duration.js";
8
9
  import { DeliverdError } from "./errors.js";
9
10
  import type {
11
+ CollectedAnswers,
10
12
  CreateApprovalInput,
13
+ CreateCollectionInput,
11
14
  CreateReviewInput,
12
15
  Decision,
13
16
  PublishReportInput,
@@ -18,6 +21,7 @@ import type {
18
21
  export { Approval, Approvals, POLL_SCHEDULE, type WaitOptions } from "./approvals.js";
19
22
  export { Comments, Reports } from "./reports.js";
20
23
  export { Review, Reviews, type ReviewWaitOptions } from "./reviews.js";
24
+ export { Collection, Collections, type CollectWaitOptions } from "./collections.js";
21
25
  export {
22
26
  constructEvent,
23
27
  DELIVERY_HEADER,
@@ -88,6 +92,24 @@ export interface ReviewOptions extends Omit<CreateReviewInput, "expiresAt"> {
88
92
  reuse?: boolean;
89
93
  }
90
94
 
95
+ /** Everything `collect()` takes, plus the conveniences it adds on top. */
96
+ export interface CollectOptions extends Omit<CreateCollectionInput, "expiresAt"> {
97
+ /** `"4h"`, `"30m"`, `"2d"`, or milliseconds. Default 24 hours. */
98
+ expiresIn?: Duration;
99
+ /** An exact moment instead, if you have one. */
100
+ expiresAt?: string;
101
+ /** Called after each poll — a progress line in a CLI. */
102
+ onPoll?: CollectWaitOptions["onPoll"];
103
+ /** Give up waiting after this. The request stays open until it expires. */
104
+ timeout?: Duration;
105
+ signal?: AbortSignal;
106
+ /**
107
+ * With an `externalId`, reuse an existing request rather than filing a
108
+ * second one, so a restarted agent does not ask the same people twice.
109
+ */
110
+ reuse?: boolean;
111
+ }
112
+
91
113
  /**
92
114
  * Deliverd: you build the action, Deliverd handles the human.
93
115
  *
@@ -110,6 +132,7 @@ export interface ReviewOptions extends Omit<CreateReviewInput, "expiresAt"> {
110
132
  export class Deliverd {
111
133
  readonly approvals: Approvals;
112
134
  readonly reviews: Reviews;
135
+ readonly collections: Collections;
113
136
  readonly reports: Reports;
114
137
  readonly comments: Comments;
115
138
  readonly webhooks: Webhooks;
@@ -131,6 +154,7 @@ export class Deliverd {
131
154
 
132
155
  this.approvals = new Approvals(this.http);
133
156
  this.reviews = new Reviews(this.http);
157
+ this.collections = new Collections(this.http);
134
158
  this.reports = new Reports(this.http);
135
159
  this.comments = new Comments(this.http);
136
160
  this.webhooks = new Webhooks();
@@ -258,6 +282,62 @@ export class Deliverd {
258
282
  return settled.toOutcome();
259
283
  }
260
284
 
285
+ /**
286
+ * Ask people for what you do not have, and wait for it.
287
+ *
288
+ * `approve()` asks permission, `review()` asks judgement, and this asks for
289
+ * a fact — a figure, a date, a choice between options, the sentence only
290
+ * they can write.
291
+ *
292
+ * ```ts
293
+ * const { answers } = await deliverd.collect({
294
+ * title: "Before I file the Q3 return",
295
+ * respondents: ["finance@firm.example"],
296
+ * questions: [
297
+ * { prompt: "Headcount at 30 September", kind: "number" },
298
+ * { prompt: "Any disposals in the quarter?", kind: "boolean" },
299
+ * ],
300
+ * });
301
+ * ```
302
+ *
303
+ * `answers` is keyed by the question you asked. Check `complete` before you
304
+ * use it: a request that expired has whatever arrived and no more, and the
305
+ * thing you do without the figure is usually not the thing you do with it.
306
+ */
307
+ async collect(options: CollectOptions): Promise<CollectedAnswers> {
308
+ const { expiresIn, timeout, onPoll, signal, reuse, ...input } = options;
309
+
310
+ if (input.externalId && reuse !== false) {
311
+ const existing = await this.collections.findByExternalId(input.externalId, signal);
312
+ if (existing) {
313
+ const settled = await existing.wait({
314
+ onPoll,
315
+ signal,
316
+ timeout: durationOrUndefined(timeout),
317
+ ...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
318
+ });
319
+ return settled.toCollected();
320
+ }
321
+ }
322
+
323
+ const collection = await this.collections.create(
324
+ {
325
+ ...input,
326
+ expiresAt:
327
+ options.expiresAt ??
328
+ new Date(Date.now() + durationMs(expiresIn ?? DEFAULT_EXPIRY)).toISOString(),
329
+ },
330
+ signal
331
+ );
332
+ const settled = await collection.wait({
333
+ onPoll,
334
+ signal,
335
+ timeout: durationOrUndefined(timeout) ?? (this.development ? 2_000 : undefined),
336
+ ...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
337
+ });
338
+ return settled.toCollected();
339
+ }
340
+
261
341
  /** Publish HTML to a secure URL. The other half of the product, one call in. */
262
342
  publish(input: PublishReportInput, signal?: AbortSignal): Promise<PublishResult> {
263
343
  return this.reports.publish(input, signal);
package/src/types.ts CHANGED
@@ -205,7 +205,9 @@ export type WebhookEventName =
205
205
  | "approval.answered"
206
206
  | "review.requested"
207
207
  | "review.approved"
208
- | "review.changes_requested";
208
+ | "review.changes_requested"
209
+ | "collection.requested"
210
+ | "collection.completed";
209
211
 
210
212
  export interface WebhookEvent {
211
213
  event: WebhookEventName;
@@ -310,3 +312,117 @@ export interface ListReviewsInput {
310
312
  reportId?: string;
311
313
  limit?: number;
312
314
  }
315
+
316
+ /* ── Collections ──────────────────────────────────────────────────────────── */
317
+
318
+ export type CollectionStatus = "pending" | "complete" | "expired" | "cancelled";
319
+
320
+ export type QuestionKind =
321
+ | "text"
322
+ | "long_text"
323
+ | "number"
324
+ | "date"
325
+ | "choice"
326
+ | "multi_choice"
327
+ | "boolean";
328
+
329
+ /** What an answer can hold, shaped by its question's kind. */
330
+ export type AnswerValue = string | number | boolean | string[];
331
+
332
+ export interface QuestionInput {
333
+ /** The question, as you would ask it out loud. */
334
+ prompt: string;
335
+ /** The sentence under the field that stops the wrong answer being given. */
336
+ help?: string;
337
+ kind: QuestionKind;
338
+ /** Required unless you say otherwise; a required question blocks submission. */
339
+ required?: boolean;
340
+ /** For `choice` and `multi_choice`. At least two, or it is not a question. */
341
+ options?: string[];
342
+ }
343
+
344
+ export interface CreateCollectionInput {
345
+ /** What you need, as a headline the person sees first. */
346
+ title: string;
347
+ /** Why you are asking, shown above the questions. */
348
+ instructions?: string;
349
+ questions: QuestionInput[];
350
+ /**
351
+ * Emails or user ids. An active member, or a guest the organisation already
352
+ * knows — anyone else is refused rather than emailed.
353
+ */
354
+ respondents: string[];
355
+ /** How many submitted replies complete it; everyone asked, when omitted. */
356
+ requiredResponses?: number;
357
+ /** A published report the request is about. */
358
+ reportId?: string;
359
+ /** Shown to the person, and what the single reminder is measured against. */
360
+ dueAt?: string;
361
+ /** After this the request closes unanswered. ISO 8601. */
362
+ expiresAt?: string;
363
+ externalId?: string;
364
+ metadata?: Record<string, unknown>;
365
+ }
366
+
367
+ export interface CollectionQuestion {
368
+ id: string;
369
+ prompt: string;
370
+ help: string | null;
371
+ kind: QuestionKind;
372
+ required: boolean;
373
+ options: string[];
374
+ }
375
+
376
+ export interface CollectionReply {
377
+ /** Who answered, as a name rather than an id. */
378
+ respondent: string;
379
+ status: "pending" | "submitted";
380
+ submittedAt: string | null;
381
+ /** Empty until they submit: a half-typed draft is not what they meant to say. */
382
+ answers: { question: string; kind: QuestionKind; value: AnswerValue }[];
383
+ }
384
+
385
+ export interface CollectionData {
386
+ id: string;
387
+ status: CollectionStatus;
388
+ /** The page the person fills in. */
389
+ url: string;
390
+ title: string;
391
+ instructions: string | null;
392
+ reportId: string | null;
393
+ externalId: string | null;
394
+ metadata: Record<string, unknown>;
395
+ requestedBy: string;
396
+ requiredResponses: number;
397
+ questions: CollectionQuestion[];
398
+ responses: CollectionReply[];
399
+ submittedCount: number;
400
+ askedCount: number;
401
+ settledAt: string | null;
402
+ dueAt: string | null;
403
+ expiresAt: string | null;
404
+ createdAt: string;
405
+ }
406
+
407
+ /** The answers, flattened — what `collect()` hands back. */
408
+ export interface CollectedAnswers {
409
+ /** True when enough people replied; false if it expired or was withdrawn. */
410
+ complete: boolean;
411
+ status: Exclude<CollectionStatus, "pending">;
412
+ /** Every submitted reply, in the order they arrived. */
413
+ responses: CollectionReply[];
414
+ /**
415
+ * The first submitted answer to each question, by its prompt — the shape
416
+ * most callers want when they asked one person for three facts.
417
+ */
418
+ answers: Record<string, AnswerValue>;
419
+ id: string;
420
+ url: string;
421
+ collection: CollectionData;
422
+ }
423
+
424
+ export interface ListCollectionsInput {
425
+ status?: CollectionStatus;
426
+ externalId?: string;
427
+ limit?: number;
428
+ }