@deliverd/sdk 0.13.0 → 0.15.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/types.ts CHANGED
@@ -436,12 +436,66 @@ export type Decision = {
436
436
  export interface ListApprovalsInput {
437
437
  status?: ApprovalStatus;
438
438
  externalId?: string;
439
+ /**
440
+ * The requests naming one person — a member's id or email, or an admitted
441
+ * guest's email. An approver's inbox, to render in your own product.
442
+ */
443
+ approver?: string;
439
444
  /** One page of this size. Leave it unset to get every row. */
440
445
  limit?: number;
441
446
  /** `nextCursor` from a previous page. Only meaningful with `limit`. */
442
447
  cursor?: string;
443
448
  }
444
449
 
450
+ /* ── Decision sessions ───────────────────────────────────────────────────── */
451
+
452
+ /**
453
+ * A page on which one approver decides one request, inside your product.
454
+ * `hosted` gives you a `url` to send them to; `embedded` gives you a
455
+ * `clientSecret` to mount with `https://deliverd.dev/elements/v1.js`.
456
+ */
457
+ export interface CreateDecisionSessionInput {
458
+ /** The approver, by email or user id. They must already be on the request. */
459
+ approver: string;
460
+ /** Defaults to `hosted`. */
461
+ mode?: "hosted" | "embedded";
462
+ /**
463
+ * Embedded only: the site that frames it, such as `https://app.example.com`.
464
+ * On the organisation's embedding allow-list, or `http://localhost` while
465
+ * you develop.
466
+ */
467
+ origin?: string;
468
+ /** Hosted only: where to send them afterwards. `deliverd_session` and `deliverd_decision` are added. */
469
+ returnUrl?: string;
470
+ /** Seconds, 60 to 86400. Never past the request's own deadline. Defaults to an hour. */
471
+ expiresIn?: number;
472
+ }
473
+
474
+ export type DecisionSessionStatus = "open" | "verified" | "complete" | "expired";
475
+
476
+ export interface DecisionSession {
477
+ id: string;
478
+ object: "decision_session";
479
+ approvalId: string;
480
+ approver: { type: "member" | "guest"; email: string };
481
+ mode: "hosted" | "embedded";
482
+ origin: string | null;
483
+ returnUrl: string | null;
484
+ /** The page, with the secret in it. Returned once, when the session is made. */
485
+ url?: string;
486
+ /** What `Deliverd.mountDecision` takes. Returned once, when the session is made. */
487
+ clientSecret?: string;
488
+ /** `verified` once the approver has confirmed who they are; `complete` once they have decided. */
489
+ status: DecisionSessionStatus;
490
+ decision: "approved" | "rejected" | "changes_requested" | null;
491
+ /** The request's own status, which another approver may have settled. */
492
+ approvalStatus: ApprovalStatus;
493
+ expiresAt: string;
494
+ verifiedAt: string | null;
495
+ completedAt: string | null;
496
+ createdAt: string;
497
+ }
498
+
445
499
  /* ── Reports ─────────────────────────────────────────────────────────────── */
446
500
 
447
501
  export interface InlineFile {
@@ -465,6 +519,19 @@ export interface PublishReportInput {
465
519
  changeSummary?: string;
466
520
  /** Publish only if this is still the current version; 0 claims a new slug. */
467
521
  expectedVersion?: number;
522
+ /**
523
+ * The flow this report belongs to, from `flows.create()`. Set on the first
524
+ * publish; a new version keeps whatever flow the report already has.
525
+ */
526
+ flowId?: string;
527
+ /**
528
+ * The task (an objective or a side task) this report is written for. It is
529
+ * then listed on the task and returned in `task.context()`, so the next
530
+ * agent publishes a new version rather than a second report. A later
531
+ * publish naming another task moves it; leaving this out keeps it where it
532
+ * is. Needs `tasks:read` on the key.
533
+ */
534
+ taskId?: string;
468
535
  uploadId?: string;
469
536
  content?: string;
470
537
  files?: InlineFile[];
@@ -481,6 +548,7 @@ export type UpdateReportInput = Pick<
481
548
  | "sourceModel"
482
549
  | "changeSummary"
483
550
  | "expectedVersion"
551
+ | "taskId"
484
552
  >;
485
553
 
486
554
  export interface ReportData {
@@ -490,6 +558,8 @@ export interface ReportData {
490
558
  url: string;
491
559
  status: string;
492
560
  currentVersion: number | null;
561
+ /** The task this report was written for, when it was published with one. */
562
+ taskId?: string | null;
493
563
  [key: string]: unknown;
494
564
  }
495
565
 
@@ -695,6 +765,92 @@ export interface WebhookEvent {
695
765
  data: Record<string, unknown>;
696
766
  }
697
767
 
768
+ /**
769
+ * How an endpoint's body is shaped: the signed JSON envelope, a Slack Block
770
+ * Kit message for an Incoming Webhook, or a Teams Adaptive Card for a
771
+ * Workflows webhook. The signature headers are sent with all three.
772
+ */
773
+ export type WebhookEndpointFormat = "json" | "slack" | "teams";
774
+
775
+ /** An organisation's webhook endpoint, as `deliverd.webhookEndpoints` reads it. Never its secret. */
776
+ export interface WebhookEndpoint {
777
+ id: string;
778
+ url: string;
779
+ description: string | null;
780
+ /** Empty means every event, including ones added later, except the opt-in ones. */
781
+ events: WebhookEventName[];
782
+ format: WebhookEndpointFormat;
783
+ enabled: boolean;
784
+ /** Consecutive failed deliveries. At twenty the endpoint is switched off. */
785
+ failureCount: number;
786
+ lastSuccessAt: string | null;
787
+ lastFailureAt: string | null;
788
+ lastError: string | null;
789
+ createdAt: string;
790
+ }
791
+
792
+ /**
793
+ * What `webhookEndpoints.create()` returns: the endpoint and its signing
794
+ * secret. **The only time the secret is returned** — no other call carries
795
+ * it, and it cannot be retrieved afterwards. Keep it with your receiver and
796
+ * pass it to `constructEvent()`.
797
+ */
798
+ export interface CreatedWebhookEndpoint {
799
+ id: string;
800
+ url: string;
801
+ description: string | null;
802
+ events: WebhookEventName[];
803
+ format: WebhookEndpointFormat;
804
+ enabled: boolean;
805
+ failureCount: number;
806
+ lastSuccessAt: string | null;
807
+ lastFailureAt: string | null;
808
+ lastError: string | null;
809
+ createdAt: string;
810
+ /** `dlvw_…`. Shown once. */
811
+ secret: string;
812
+ }
813
+
814
+ export interface CreateWebhookEndpointInput {
815
+ /** HTTPS, on a public host. */
816
+ url: string;
817
+ /** Leave it out, or send `[]`, for every event except the opt-in ones. */
818
+ events?: WebhookEventName[];
819
+ description?: string | null;
820
+ /** Default `"json"`. */
821
+ format?: WebhookEndpointFormat;
822
+ }
823
+
824
+ /** Only what you send changes; send at least one. The secret cannot be changed. */
825
+ export interface UpdateWebhookEndpointInput {
826
+ url?: string;
827
+ events?: WebhookEventName[];
828
+ description?: string | null;
829
+ format?: WebhookEndpointFormat;
830
+ /** Turning it back on clears its run of failures. */
831
+ enabled?: boolean;
832
+ }
833
+
834
+ export interface TestWebhookEndpointInput {
835
+ /** Default `"report.published"`. */
836
+ event?: WebhookEventName;
837
+ }
838
+
839
+ /** What the endpoint said to a test send. `delivered: false` is an answer, not an error. */
840
+ export interface WebhookTestResult {
841
+ delivered: boolean;
842
+ /** Null when it could not be reached. */
843
+ responseStatus: number | null;
844
+ error: string | null;
845
+ }
846
+
847
+ export interface ListWebhookEndpointsInput {
848
+ /** One page of this size. Leave it unset to get every endpoint. */
849
+ limit?: number;
850
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
851
+ cursor?: string;
852
+ }
853
+
698
854
  /* ── Reviews ──────────────────────────────────────────────────────────────── */
699
855
 
700
856
  export type ReviewStatus =
@@ -1258,10 +1414,25 @@ export interface TaskContext {
1258
1414
  snapshot: TaskSnapshot | null;
1259
1415
  relevantFindings: TaskContextFinding[];
1260
1416
  sideTasks: TaskContextSideTasks;
1417
+ /**
1418
+ * Reports published for this task, newest first, up to ten. Revise one with
1419
+ * `reports.update()` rather than publishing a second on the same thing.
1420
+ */
1421
+ reports: TaskContextReport[];
1261
1422
  /** One paragraph to say back to yourself to re-anchor on the objective. */
1262
1423
  reanchor: string;
1263
1424
  }
1264
1425
 
1426
+ /** A report published for a task, as its context names it. */
1427
+ export interface TaskContextReport {
1428
+ id: string;
1429
+ title: string;
1430
+ url: string;
1431
+ /** The live version; null until one has gone live. */
1432
+ version: number | null;
1433
+ publishedAt: string | null;
1434
+ }
1435
+
1265
1436
  export interface TaskGraph {
1266
1437
  root: TaskData;
1267
1438
  nodes: TaskNode[];
@@ -0,0 +1,115 @@
1
+ import type { HttpClient } from "./http.js";
2
+ import { listOrCollect, type PageOf } from "./paging.js";
3
+ import type {
4
+ CreatedWebhookEndpoint,
5
+ CreateWebhookEndpointInput,
6
+ ListWebhookEndpointsInput,
7
+ TestWebhookEndpointInput,
8
+ UpdateWebhookEndpointInput,
9
+ WebhookEndpoint,
10
+ WebhookTestResult,
11
+ } from "./types.js";
12
+
13
+ /**
14
+ * The organisation's webhook endpoints: where its events are sent.
15
+ *
16
+ * ```ts
17
+ * const endpoint = await deliverd.webhookEndpoints.create({
18
+ * url: "https://hooks.example.com/deliverd",
19
+ * events: ["approval.approved", "approval.rejected"],
20
+ * });
21
+ * saveSecret(endpoint.secret); // returned this once, never again
22
+ * ```
23
+ *
24
+ * **Needs an administrator's key with `webhooks:manage`.** An endpoint
25
+ * receives every event in the organisation, so the API checks the key's
26
+ * holder is an owner or an administrator on every call, and refuses an agent
27
+ * key outright (`agent_not_permitted`) — reads included.
28
+ *
29
+ * Distinct from `deliverd.webhooks`, which verifies what arrives at an
30
+ * endpoint and makes no request at all.
31
+ */
32
+ export class WebhookEndpoints {
33
+ constructor(private readonly http: HttpClient) {}
34
+
35
+ /**
36
+ * Newest first. With no `limit` this is every endpoint; with a `limit` it is
37
+ * one page of that size, and `listPage` hands back the cursor to continue from.
38
+ */
39
+ async list(input: ListWebhookEndpointsInput = {}, signal?: AbortSignal): Promise<WebhookEndpoint[]> {
40
+ return listOrCollect(input, (q) => this.listPage({ ...input, ...q }, signal));
41
+ }
42
+
43
+ /** One page, and the cursor to continue from — null when it is the end. */
44
+ async listPage(
45
+ input: ListWebhookEndpointsInput = {},
46
+ signal?: AbortSignal
47
+ ): Promise<PageOf<WebhookEndpoint>> {
48
+ const { webhookEndpoints, nextCursor } = await this.http.request<{
49
+ webhookEndpoints: WebhookEndpoint[];
50
+ nextCursor: string | null;
51
+ }>({
52
+ method: "GET",
53
+ path: "/webhook-endpoints",
54
+ query: { limit: input.limit, cursor: input.cursor },
55
+ signal,
56
+ });
57
+ return { items: webhookEndpoints, nextCursor };
58
+ }
59
+
60
+ /**
61
+ * Add an endpoint. The result carries `secret`, **the only time it is
62
+ * returned**: keep it with whatever receives the events. A retried call
63
+ * replays this same response, secret included, rather than adding a second
64
+ * endpoint.
65
+ */
66
+ create(input: CreateWebhookEndpointInput, signal?: AbortSignal): Promise<CreatedWebhookEndpoint> {
67
+ return this.http.request({ method: "POST", path: "/webhook-endpoints", body: input, signal });
68
+ }
69
+
70
+ /** One endpoint, with its delivery health. Never its secret. */
71
+ get(id: string, signal?: AbortSignal): Promise<WebhookEndpoint> {
72
+ return this.http.request({
73
+ method: "GET",
74
+ path: `/webhook-endpoints/${encodeURIComponent(id)}`,
75
+ signal,
76
+ });
77
+ }
78
+
79
+ /**
80
+ * Change the address, events, description or format, or turn it off and on.
81
+ * Only what you send changes. Turning one back on clears its run of failures.
82
+ */
83
+ update(id: string, input: UpdateWebhookEndpointInput, signal?: AbortSignal): Promise<WebhookEndpoint> {
84
+ return this.http.request({
85
+ method: "PATCH",
86
+ path: `/webhook-endpoints/${encodeURIComponent(id)}`,
87
+ body: input,
88
+ signal,
89
+ });
90
+ }
91
+
92
+ /** Remove it, and its delivery log. `update(id, { enabled: false })` pauses it instead. */
93
+ delete(id: string, signal?: AbortSignal): Promise<void> {
94
+ return this.http.request({
95
+ method: "DELETE",
96
+ path: `/webhook-endpoints/${encodeURIComponent(id)}`,
97
+ signal,
98
+ });
99
+ }
100
+
101
+ /**
102
+ * Send it one event now — `"test": true`, obviously fake ids — and get back
103
+ * what it answered. Never retried, and never counted toward switching the
104
+ * endpoint off. `delivered: false` is an answer about the endpoint; this
105
+ * throws only when the call itself is refused.
106
+ */
107
+ test(id: string, input: TestWebhookEndpointInput = {}, signal?: AbortSignal): Promise<WebhookTestResult> {
108
+ return this.http.request({
109
+ method: "POST",
110
+ path: `/webhook-endpoints/${encodeURIComponent(id)}/test`,
111
+ body: input,
112
+ signal,
113
+ });
114
+ }
115
+ }