@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/README.md +83 -3
- 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 +5 -0
- package/dist/index.d.ts +7 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -2
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +1566 -0
- package/dist/types.d.ts +160 -1
- 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 +4 -0
- package/src/index.ts +9 -2
- package/src/released.ts +1566 -0
- package/src/types.ts +171 -0
- package/src/webhook-endpoints.ts +115 -0
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
|
+
}
|