@deliverd/sdk 0.14.0 → 0.16.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 +65 -4
- package/dist/approvals.d.ts +17 -1
- package/dist/approvals.d.ts.map +1 -1
- package/dist/approvals.js +36 -1
- package/dist/dev.d.ts.map +1 -1
- package/dist/dev.js +3 -0
- package/dist/index.d.ts +8 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -3
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +1634 -0
- package/dist/reports.d.ts +9 -3
- package/dist/reports.d.ts.map +1 -1
- package/dist/reports.js +14 -3
- package/dist/types.d.ts +140 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/webhook-endpoints.d.ts +57 -0
- package/dist/webhook-endpoints.d.ts.map +1 -0
- package/dist/webhook-endpoints.js +94 -0
- package/package.json +1 -1
- package/src/approvals.ts +43 -1
- package/src/dev.ts +2 -0
- package/src/index.ts +10 -3
- package/src/released.ts +1634 -0
- package/src/reports.ts +20 -3
- package/src/types.ts +152 -0
- package/src/webhook-endpoints.ts +115 -0
package/src/reports.ts
CHANGED
|
@@ -10,6 +10,7 @@ import type {
|
|
|
10
10
|
ReportData,
|
|
11
11
|
ScheduleSummary,
|
|
12
12
|
SendResult,
|
|
13
|
+
ShareOptions,
|
|
13
14
|
UpdateReportInput,
|
|
14
15
|
EvidencePack,
|
|
15
16
|
} from "./types.js";
|
|
@@ -122,12 +123,28 @@ export class Reports {
|
|
|
122
123
|
});
|
|
123
124
|
}
|
|
124
125
|
|
|
125
|
-
/**
|
|
126
|
-
|
|
126
|
+
/**
|
|
127
|
+
* Grant people, teams or groups access. Filing is not access; this is.
|
|
128
|
+
*
|
|
129
|
+
* `{ capability: "comment" }` lets them comment as well as read; leave it
|
|
130
|
+
* out for view. A signal in third place, as before options existed, still
|
|
131
|
+
* works.
|
|
132
|
+
*/
|
|
133
|
+
async share(
|
|
134
|
+
idOrSlug: string,
|
|
135
|
+
audience: unknown,
|
|
136
|
+
options?: ShareOptions | AbortSignal,
|
|
137
|
+
signal?: AbortSignal
|
|
138
|
+
): Promise<unknown[]> {
|
|
139
|
+
if (options instanceof AbortSignal) {
|
|
140
|
+
signal = options;
|
|
141
|
+
options = undefined;
|
|
142
|
+
}
|
|
143
|
+
const capability = options?.capability;
|
|
127
144
|
const { granted } = await this.http.request<{ granted: unknown[] }>({
|
|
128
145
|
method: "POST",
|
|
129
146
|
path: `/reports/${encodeURIComponent(idOrSlug)}/share`,
|
|
130
|
-
body: { audience },
|
|
147
|
+
body: capability ? { audience, capability } : { audience },
|
|
131
148
|
signal,
|
|
132
149
|
});
|
|
133
150
|
return granted;
|
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 {
|
|
@@ -558,6 +612,18 @@ export interface SendResult {
|
|
|
558
612
|
alreadyHadAccess: string[];
|
|
559
613
|
}
|
|
560
614
|
|
|
615
|
+
/**
|
|
616
|
+
* What a share lets its audience do. `"view"` is the default.
|
|
617
|
+
*
|
|
618
|
+
* "Can manage", which lets someone share the report on, is not here: it is a
|
|
619
|
+
* person's decision, made in the app, and the API refuses it from a key.
|
|
620
|
+
*/
|
|
621
|
+
export type ShareCapability = "view" | "comment";
|
|
622
|
+
|
|
623
|
+
export interface ShareOptions {
|
|
624
|
+
capability?: ShareCapability;
|
|
625
|
+
}
|
|
626
|
+
|
|
561
627
|
/* ── Schedules ───────────────────────────────────────────────────────────── */
|
|
562
628
|
|
|
563
629
|
/**
|
|
@@ -711,6 +777,92 @@ export interface WebhookEvent {
|
|
|
711
777
|
data: Record<string, unknown>;
|
|
712
778
|
}
|
|
713
779
|
|
|
780
|
+
/**
|
|
781
|
+
* How an endpoint's body is shaped: the signed JSON envelope, a Slack Block
|
|
782
|
+
* Kit message for an Incoming Webhook, or a Teams Adaptive Card for a
|
|
783
|
+
* Workflows webhook. The signature headers are sent with all three.
|
|
784
|
+
*/
|
|
785
|
+
export type WebhookEndpointFormat = "json" | "slack" | "teams";
|
|
786
|
+
|
|
787
|
+
/** An organisation's webhook endpoint, as `deliverd.webhookEndpoints` reads it. Never its secret. */
|
|
788
|
+
export interface WebhookEndpoint {
|
|
789
|
+
id: string;
|
|
790
|
+
url: string;
|
|
791
|
+
description: string | null;
|
|
792
|
+
/** Empty means every event, including ones added later, except the opt-in ones. */
|
|
793
|
+
events: WebhookEventName[];
|
|
794
|
+
format: WebhookEndpointFormat;
|
|
795
|
+
enabled: boolean;
|
|
796
|
+
/** Consecutive failed deliveries. At twenty the endpoint is switched off. */
|
|
797
|
+
failureCount: number;
|
|
798
|
+
lastSuccessAt: string | null;
|
|
799
|
+
lastFailureAt: string | null;
|
|
800
|
+
lastError: string | null;
|
|
801
|
+
createdAt: string;
|
|
802
|
+
}
|
|
803
|
+
|
|
804
|
+
/**
|
|
805
|
+
* What `webhookEndpoints.create()` returns: the endpoint and its signing
|
|
806
|
+
* secret. **The only time the secret is returned** — no other call carries
|
|
807
|
+
* it, and it cannot be retrieved afterwards. Keep it with your receiver and
|
|
808
|
+
* pass it to `constructEvent()`.
|
|
809
|
+
*/
|
|
810
|
+
export interface CreatedWebhookEndpoint {
|
|
811
|
+
id: string;
|
|
812
|
+
url: string;
|
|
813
|
+
description: string | null;
|
|
814
|
+
events: WebhookEventName[];
|
|
815
|
+
format: WebhookEndpointFormat;
|
|
816
|
+
enabled: boolean;
|
|
817
|
+
failureCount: number;
|
|
818
|
+
lastSuccessAt: string | null;
|
|
819
|
+
lastFailureAt: string | null;
|
|
820
|
+
lastError: string | null;
|
|
821
|
+
createdAt: string;
|
|
822
|
+
/** `dlvw_…`. Shown once. */
|
|
823
|
+
secret: string;
|
|
824
|
+
}
|
|
825
|
+
|
|
826
|
+
export interface CreateWebhookEndpointInput {
|
|
827
|
+
/** HTTPS, on a public host. */
|
|
828
|
+
url: string;
|
|
829
|
+
/** Leave it out, or send `[]`, for every event except the opt-in ones. */
|
|
830
|
+
events?: WebhookEventName[];
|
|
831
|
+
description?: string | null;
|
|
832
|
+
/** Default `"json"`. */
|
|
833
|
+
format?: WebhookEndpointFormat;
|
|
834
|
+
}
|
|
835
|
+
|
|
836
|
+
/** Only what you send changes; send at least one. The secret cannot be changed. */
|
|
837
|
+
export interface UpdateWebhookEndpointInput {
|
|
838
|
+
url?: string;
|
|
839
|
+
events?: WebhookEventName[];
|
|
840
|
+
description?: string | null;
|
|
841
|
+
format?: WebhookEndpointFormat;
|
|
842
|
+
/** Turning it back on clears its run of failures. */
|
|
843
|
+
enabled?: boolean;
|
|
844
|
+
}
|
|
845
|
+
|
|
846
|
+
export interface TestWebhookEndpointInput {
|
|
847
|
+
/** Default `"report.published"`. */
|
|
848
|
+
event?: WebhookEventName;
|
|
849
|
+
}
|
|
850
|
+
|
|
851
|
+
/** What the endpoint said to a test send. `delivered: false` is an answer, not an error. */
|
|
852
|
+
export interface WebhookTestResult {
|
|
853
|
+
delivered: boolean;
|
|
854
|
+
/** Null when it could not be reached. */
|
|
855
|
+
responseStatus: number | null;
|
|
856
|
+
error: string | null;
|
|
857
|
+
}
|
|
858
|
+
|
|
859
|
+
export interface ListWebhookEndpointsInput {
|
|
860
|
+
/** One page of this size. Leave it unset to get every endpoint. */
|
|
861
|
+
limit?: number;
|
|
862
|
+
/** `nextCursor` from a previous page. Only meaningful with `limit`. */
|
|
863
|
+
cursor?: string;
|
|
864
|
+
}
|
|
865
|
+
|
|
714
866
|
/* ── Reviews ──────────────────────────────────────────────────────────────── */
|
|
715
867
|
|
|
716
868
|
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
|
+
}
|