@deliverd/sdk 0.14.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 {
@@ -711,6 +765,92 @@ export interface WebhookEvent {
711
765
  data: Record<string, unknown>;
712
766
  }
713
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
+
714
854
  /* ── Reviews ──────────────────────────────────────────────────────────────── */
715
855
 
716
856
  export type ReviewStatus =
@@ -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
+ }