@deliverd/sdk 0.1.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/LICENSE +21 -0
- package/README.md +282 -0
- package/dist/approvals.d.ts +133 -0
- package/dist/approvals.d.ts.map +1 -0
- package/dist/approvals.js +228 -0
- package/dist/dev.d.ts +46 -0
- package/dist/dev.d.ts.map +1 -0
- package/dist/dev.js +147 -0
- package/dist/duration.d.ts +10 -0
- package/dist/duration.d.ts.map +1 -0
- package/dist/duration.js +10 -0
- package/dist/errors.d.ts +44 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +58 -0
- package/dist/http.d.ts +45 -0
- package/dist/http.d.ts.map +1 -0
- package/dist/http.js +135 -0
- package/dist/index.d.ts +103 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +144 -0
- package/dist/messages.d.ts +24 -0
- package/dist/messages.d.ts.map +1 -0
- package/dist/messages.js +70 -0
- package/dist/reports.d.ts +76 -0
- package/dist/reports.d.ts.map +1 -0
- package/dist/reports.js +168 -0
- package/dist/types.d.ts +179 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +11 -0
- package/dist/webhooks.d.ts +49 -0
- package/dist/webhooks.d.ts.map +1 -0
- package/dist/webhooks.js +77 -0
- package/package.json +55 -0
- package/src/approvals.ts +286 -0
- package/src/dev.ts +213 -0
- package/src/duration.ts +21 -0
- package/src/errors.ts +62 -0
- package/src/http.ts +185 -0
- package/src/index.ts +212 -0
- package/src/messages.ts +78 -0
- package/src/reports.ts +217 -0
- package/src/types.ts +213 -0
- package/src/webhooks.ts +98 -0
package/src/messages.ts
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a failure says.
|
|
3
|
+
*
|
|
4
|
+
* An error is part of the interface, and `ERR_POLICY_SUBJECT_RESOLUTION_FAILED`
|
|
5
|
+
* is an interface that tells a developer to go and read something. These say
|
|
6
|
+
* what happened, why, and the one thing to do next — because the person
|
|
7
|
+
* reading it is stuck, at a keyboard, and does not want a search engine.
|
|
8
|
+
*
|
|
9
|
+
* Keyed on the codes the API actually returns. Anything unlisted keeps the
|
|
10
|
+
* API's own message, which is written for a person too.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
export interface Explanation {
|
|
14
|
+
/** Replaces the API's message when we can say it better. */
|
|
15
|
+
message?: string;
|
|
16
|
+
/** The line under it: what to do. */
|
|
17
|
+
hint: string;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export const EXPLANATIONS: Record<string, Explanation> = {
|
|
21
|
+
no_api_key: {
|
|
22
|
+
message: "No API key.",
|
|
23
|
+
hint: "Set DELIVERD_API_KEY in your environment, or pass { apiKey } — or use { mode: \"development\" } to run without one.",
|
|
24
|
+
},
|
|
25
|
+
auth_error: {
|
|
26
|
+
message: "That API key was not accepted.",
|
|
27
|
+
hint: "Check DELIVERD_API_KEY. Keys start with dlv_ and are created in Settings → API tokens.",
|
|
28
|
+
},
|
|
29
|
+
insufficient_scope: {
|
|
30
|
+
hint: "Reissue the key with the scope named above. A key issued before a scope existed does not have it.",
|
|
31
|
+
},
|
|
32
|
+
unknown_approver: {
|
|
33
|
+
message: "No approver could be found for this request.",
|
|
34
|
+
hint: "Everyone in `approvers` must be an active member of your organisation, named by email or user id. Invite them first, or leave `approvers` out and your owners and admins decide.",
|
|
35
|
+
},
|
|
36
|
+
self_approval: {
|
|
37
|
+
message: "You cannot approve your own request.",
|
|
38
|
+
hint: "Name somebody else in `approvers`, or leave it out so your organisation's owners and admins decide.",
|
|
39
|
+
},
|
|
40
|
+
not_approver: {
|
|
41
|
+
hint: "Only the people named on the request can decide it.",
|
|
42
|
+
},
|
|
43
|
+
not_requester: {
|
|
44
|
+
message: "Only the requester can answer a question on their own request.",
|
|
45
|
+
hint: "Use the same key that created the approval.",
|
|
46
|
+
},
|
|
47
|
+
not_pending: {
|
|
48
|
+
message: "That request was already decided.",
|
|
49
|
+
hint: "Read its status rather than deciding again; a decision is final.",
|
|
50
|
+
},
|
|
51
|
+
expired: {
|
|
52
|
+
message: "That request expired before anyone decided it.",
|
|
53
|
+
hint: "Ask again, with a longer `expiresIn`, or chase the approver.",
|
|
54
|
+
},
|
|
55
|
+
rate_limited: {
|
|
56
|
+
message: "Too many requests.",
|
|
57
|
+
hint: "The SDK already retried and gave up. Reduce how often you poll, or wait with `approve()` rather than looping yourself.",
|
|
58
|
+
},
|
|
59
|
+
plan_limit: {
|
|
60
|
+
hint: "Your organisation's plan does not include this. Billing → Plans.",
|
|
61
|
+
},
|
|
62
|
+
network_error: {
|
|
63
|
+
hint: "Check the machine's network and `baseUrl`. Deliverd's status is at https://deliverd.dev.",
|
|
64
|
+
},
|
|
65
|
+
timeout: {
|
|
66
|
+
hint: "Nobody decided in time. The request is still open at the URL above until it expires.",
|
|
67
|
+
},
|
|
68
|
+
invalid_signature: {
|
|
69
|
+
hint: "Check the endpoint's signing secret, and that you passed the raw request body rather than a re-encoded object.",
|
|
70
|
+
},
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
/** The message as a developer should read it: what happened, then what to do. */
|
|
74
|
+
export function explain(code: string, apiMessage: string): { message: string; hint?: string } {
|
|
75
|
+
const found = EXPLANATIONS[code];
|
|
76
|
+
if (!found) return { message: apiMessage };
|
|
77
|
+
return { message: `${found.message ?? apiMessage}\n${found.hint}`, hint: found.hint };
|
|
78
|
+
}
|
package/src/reports.ts
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
import type { HttpClient } from "./http.js";
|
|
2
|
+
import type {
|
|
3
|
+
CommentThread,
|
|
4
|
+
PublishReportInput,
|
|
5
|
+
PublishResult,
|
|
6
|
+
ReportData,
|
|
7
|
+
UpdateReportInput,
|
|
8
|
+
} from "./types.js";
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* The publishing half: get what the agent wrote to the people who need it, at
|
|
12
|
+
* an address that does not change.
|
|
13
|
+
*
|
|
14
|
+
* Thin on purpose. These are the REST routes with their names spelled the way
|
|
15
|
+
* a person would say them, and nothing else — the service decides what a
|
|
16
|
+
* publish means, and an SDK that reimplemented any of it would be a second
|
|
17
|
+
* answer to the same question.
|
|
18
|
+
*/
|
|
19
|
+
export class Reports {
|
|
20
|
+
constructor(private readonly http: HttpClient) {}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Publish HTML to a secure URL.
|
|
24
|
+
*
|
|
25
|
+
* Check `result.status`: a publishing policy can hold the version for a
|
|
26
|
+
* person's approval, in which case nothing is live yet and `result.approval`
|
|
27
|
+
* names the request.
|
|
28
|
+
*/
|
|
29
|
+
publish(input: PublishReportInput, signal?: AbortSignal): Promise<PublishResult> {
|
|
30
|
+
return this.http.request({ method: "POST", path: "/reports", body: input, signal });
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** A new version of an existing report, keeping its URL and its audience. */
|
|
34
|
+
update(
|
|
35
|
+
idOrSlug: string,
|
|
36
|
+
input: UpdateReportInput,
|
|
37
|
+
signal?: AbortSignal
|
|
38
|
+
): Promise<PublishResult> {
|
|
39
|
+
return this.http.request({
|
|
40
|
+
method: "POST",
|
|
41
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/versions`,
|
|
42
|
+
body: input,
|
|
43
|
+
signal,
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
get(idOrSlug: string, signal?: AbortSignal): Promise<ReportData> {
|
|
48
|
+
return this.http.request({
|
|
49
|
+
method: "GET",
|
|
50
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}`,
|
|
51
|
+
signal,
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
async list(query?: string, signal?: AbortSignal): Promise<ReportData[]> {
|
|
56
|
+
const { reports } = await this.http.request<{ reports: ReportData[] }>({
|
|
57
|
+
method: "GET",
|
|
58
|
+
path: "/reports",
|
|
59
|
+
query: { q: query },
|
|
60
|
+
signal,
|
|
61
|
+
});
|
|
62
|
+
return reports;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Change the title, the address, or both. The old address keeps working. */
|
|
66
|
+
rename(
|
|
67
|
+
idOrSlug: string,
|
|
68
|
+
input: { title?: string; slug?: string; description?: string; workspaceId?: string },
|
|
69
|
+
signal?: AbortSignal
|
|
70
|
+
): Promise<ReportData> {
|
|
71
|
+
return this.http.request({
|
|
72
|
+
method: "PATCH",
|
|
73
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}`,
|
|
74
|
+
body: input,
|
|
75
|
+
signal,
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Grant people, teams or groups access. Filing is not access; this is. */
|
|
80
|
+
async share(idOrSlug: string, audience: unknown, signal?: AbortSignal): Promise<unknown[]> {
|
|
81
|
+
const { granted } = await this.http.request<{ granted: unknown[] }>({
|
|
82
|
+
method: "POST",
|
|
83
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/share`,
|
|
84
|
+
body: { audience },
|
|
85
|
+
signal,
|
|
86
|
+
});
|
|
87
|
+
return granted;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Stop the URL serving. `archived: false` puts it back. */
|
|
91
|
+
archive(idOrSlug: string, archived = true, signal?: AbortSignal): Promise<ReportData> {
|
|
92
|
+
return this.http.request({
|
|
93
|
+
method: "POST",
|
|
94
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/archive`,
|
|
95
|
+
body: { archived },
|
|
96
|
+
signal,
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
rollback(idOrSlug: string, version: number, signal?: AbortSignal): Promise<unknown> {
|
|
101
|
+
return this.http.request({
|
|
102
|
+
method: "POST",
|
|
103
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/rollback`,
|
|
104
|
+
body: { version },
|
|
105
|
+
signal,
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Every version, with `latestVersion` beside `currentVersion`. Pass
|
|
111
|
+
* `latestVersion` as `expectedVersion` on an update: a held or declined
|
|
112
|
+
* version takes a number without going live.
|
|
113
|
+
*/
|
|
114
|
+
versions(idOrSlug: string, signal?: AbortSignal): Promise<Record<string, unknown>> {
|
|
115
|
+
return this.http.request({
|
|
116
|
+
method: "GET",
|
|
117
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/versions`,
|
|
118
|
+
signal,
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/** Who read it and when. The detail needs the analytics plan. */
|
|
123
|
+
analytics(idOrSlug: string, signal?: AbortSignal): Promise<Record<string, unknown>> {
|
|
124
|
+
return this.http.request({
|
|
125
|
+
method: "GET",
|
|
126
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/analytics`,
|
|
127
|
+
signal,
|
|
128
|
+
});
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** Replace a dataset a living report reads. No new version, same URL. */
|
|
132
|
+
putData(
|
|
133
|
+
idOrSlug: string,
|
|
134
|
+
name: string,
|
|
135
|
+
data: unknown,
|
|
136
|
+
signal?: AbortSignal
|
|
137
|
+
): Promise<unknown> {
|
|
138
|
+
return this.http.request({
|
|
139
|
+
method: "PUT",
|
|
140
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/data/${encodeURIComponent(name)}`,
|
|
141
|
+
body: data,
|
|
142
|
+
signal,
|
|
143
|
+
});
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
listData(idOrSlug: string, signal?: AbortSignal): Promise<unknown> {
|
|
147
|
+
return this.http.request({
|
|
148
|
+
method: "GET",
|
|
149
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/data`,
|
|
150
|
+
signal,
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* The open feedback composed into one prompt, with the readers' images as
|
|
156
|
+
* signed links: everything needed to write the next version.
|
|
157
|
+
*/
|
|
158
|
+
revisionBrief(
|
|
159
|
+
idOrSlug: string,
|
|
160
|
+
input: { threadIds?: string[]; instructions?: string } = {},
|
|
161
|
+
signal?: AbortSignal
|
|
162
|
+
): Promise<Record<string, unknown>> {
|
|
163
|
+
return this.http.request({
|
|
164
|
+
method: "POST",
|
|
165
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/revision-briefs`,
|
|
166
|
+
body: input,
|
|
167
|
+
signal,
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** Reader feedback, anchored to the passage it is about. */
|
|
173
|
+
export class Comments {
|
|
174
|
+
constructor(private readonly http: HttpClient) {}
|
|
175
|
+
|
|
176
|
+
async list(
|
|
177
|
+
idOrSlug: string,
|
|
178
|
+
status: "open" | "resolved" | "all" = "open",
|
|
179
|
+
signal?: AbortSignal
|
|
180
|
+
): Promise<CommentThread[]> {
|
|
181
|
+
const { threads } = await this.http.request<{ threads: CommentThread[] }>({
|
|
182
|
+
method: "GET",
|
|
183
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/comments`,
|
|
184
|
+
query: { status },
|
|
185
|
+
signal,
|
|
186
|
+
});
|
|
187
|
+
return threads;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** `quote` anchors it to a passage; `threadId` replies to one. */
|
|
191
|
+
create(
|
|
192
|
+
idOrSlug: string,
|
|
193
|
+
input: { body: string; quote?: string; threadId?: string },
|
|
194
|
+
signal?: AbortSignal
|
|
195
|
+
): Promise<unknown> {
|
|
196
|
+
return this.http.request({
|
|
197
|
+
method: "POST",
|
|
198
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/comments`,
|
|
199
|
+
body: input,
|
|
200
|
+
signal,
|
|
201
|
+
});
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** Mark a thread resolved, with a note on what changed. */
|
|
205
|
+
resolve(
|
|
206
|
+
threadId: string,
|
|
207
|
+
input: { note?: string; reopen?: boolean } = {},
|
|
208
|
+
signal?: AbortSignal
|
|
209
|
+
): Promise<unknown> {
|
|
210
|
+
return this.http.request({
|
|
211
|
+
method: "POST",
|
|
212
|
+
path: `/comments/${encodeURIComponent(threadId)}/resolve`,
|
|
213
|
+
body: input,
|
|
214
|
+
signal,
|
|
215
|
+
});
|
|
216
|
+
}
|
|
217
|
+
}
|
package/src/types.ts
ADDED
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The API's objects, by hand.
|
|
3
|
+
*
|
|
4
|
+
* Not imported from the server's zod schemas on purpose: this package is
|
|
5
|
+
* published to npm and must not drag the monorepo's internals with it. The
|
|
6
|
+
* cost of that is drift, so `apps/web/src/lib/services/api-approvals.test.ts`
|
|
7
|
+
* holds these shapes to the schemas the API actually validates — a field added
|
|
8
|
+
* there and not here fails the build on the server side, where someone is
|
|
9
|
+
* looking.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled";
|
|
13
|
+
export type ApprovalRisk = "low" | "medium" | "high" | "critical";
|
|
14
|
+
|
|
15
|
+
/** One line of evidence, as the approval page shows it. */
|
|
16
|
+
export interface ApprovalFactor {
|
|
17
|
+
label: string;
|
|
18
|
+
status?: "ok" | "warning" | "info";
|
|
19
|
+
detail?: string;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export interface ApprovalLink {
|
|
23
|
+
label: string;
|
|
24
|
+
url: string;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export interface ApprovalQuestion {
|
|
28
|
+
id: string;
|
|
29
|
+
question: string;
|
|
30
|
+
answer: string | null;
|
|
31
|
+
askedAt: string;
|
|
32
|
+
answeredAt: string | null;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export interface ApprovalData {
|
|
36
|
+
id: string;
|
|
37
|
+
status: ApprovalStatus;
|
|
38
|
+
/** The page the approver decides on. */
|
|
39
|
+
url: string;
|
|
40
|
+
title: string;
|
|
41
|
+
description: string | null;
|
|
42
|
+
risk: ApprovalRisk;
|
|
43
|
+
factors: ApprovalFactor[];
|
|
44
|
+
links: ApprovalLink[];
|
|
45
|
+
reportId: string | null;
|
|
46
|
+
externalId: string | null;
|
|
47
|
+
metadata: Record<string, unknown>;
|
|
48
|
+
requestedBy: string;
|
|
49
|
+
approvers: string[];
|
|
50
|
+
decidedBy: string | null;
|
|
51
|
+
decidedAt: string | null;
|
|
52
|
+
/** The approver's reason, on a rejection or an approval that carried one. */
|
|
53
|
+
note: string | null;
|
|
54
|
+
expiresAt: string | null;
|
|
55
|
+
questions: ApprovalQuestion[];
|
|
56
|
+
createdAt: string;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export interface CreateApprovalInput {
|
|
60
|
+
/** What is being asked, as a headline. */
|
|
61
|
+
title: string;
|
|
62
|
+
/** Why, what it affects, what it costs — what the approver reads first. */
|
|
63
|
+
description?: string;
|
|
64
|
+
/** How the approver should weigh it. Medium when omitted. */
|
|
65
|
+
risk?: ApprovalRisk;
|
|
66
|
+
/** Evidence, one line each, shown as a checklist. */
|
|
67
|
+
factors?: ApprovalFactor[];
|
|
68
|
+
/** Where to read more. */
|
|
69
|
+
links?: ApprovalLink[];
|
|
70
|
+
/** A published report the request is about. */
|
|
71
|
+
reportId?: string;
|
|
72
|
+
/**
|
|
73
|
+
* Emails or user ids of members who may decide. The organisation's owners
|
|
74
|
+
* and admins when omitted. You cannot name yourself.
|
|
75
|
+
*/
|
|
76
|
+
approvers?: string[];
|
|
77
|
+
/** After this the request expires undecided. ISO 8601. */
|
|
78
|
+
expiresAt?: string;
|
|
79
|
+
/** Your own reference, returned unchanged and searchable. */
|
|
80
|
+
externalId?: string;
|
|
81
|
+
metadata?: Record<string, unknown>;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* The answer to `approve()`.
|
|
86
|
+
*
|
|
87
|
+
* Flat on purpose: the line after the call is `if (decision.approved)`, and
|
|
88
|
+
* anything a caller has to reach through to get there is a step this SDK
|
|
89
|
+
* exists to remove. The whole request is on `approval` when a field here does
|
|
90
|
+
* not cover it.
|
|
91
|
+
*/
|
|
92
|
+
export type Decision = {
|
|
93
|
+
/** True only for an approval. False for rejected, expired and cancelled. */
|
|
94
|
+
approved: boolean;
|
|
95
|
+
/** For a switch, and for narrowing. */
|
|
96
|
+
status: "approved" | "rejected" | "expired" | "cancelled";
|
|
97
|
+
/** Their reason, when they gave one. */
|
|
98
|
+
note: string | null;
|
|
99
|
+
decidedBy: string | null;
|
|
100
|
+
decidedAt: string | null;
|
|
101
|
+
id: string;
|
|
102
|
+
/** The page they decided on. Worth logging. */
|
|
103
|
+
url: string;
|
|
104
|
+
/** The request itself, for anything the fields above do not name. */
|
|
105
|
+
approval: unknown;
|
|
106
|
+
};
|
|
107
|
+
|
|
108
|
+
export interface ListApprovalsInput {
|
|
109
|
+
status?: ApprovalStatus;
|
|
110
|
+
externalId?: string;
|
|
111
|
+
limit?: number;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/* ── Reports ─────────────────────────────────────────────────────────────── */
|
|
115
|
+
|
|
116
|
+
export interface InlineFile {
|
|
117
|
+
path: string;
|
|
118
|
+
content: string;
|
|
119
|
+
/** `base64` for an image or a font; text otherwise. */
|
|
120
|
+
encoding?: "utf8" | "base64";
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
export interface PublishReportInput {
|
|
124
|
+
title?: string;
|
|
125
|
+
slug?: string;
|
|
126
|
+
description?: string;
|
|
127
|
+
workspaceId?: string;
|
|
128
|
+
/** Names, teams, groups or emails — resolved server-side. */
|
|
129
|
+
audience?: unknown;
|
|
130
|
+
classification?: string;
|
|
131
|
+
living?: boolean;
|
|
132
|
+
sourceTool?: string;
|
|
133
|
+
sourceModel?: string;
|
|
134
|
+
changeSummary?: string;
|
|
135
|
+
/** Publish only if this is still the current version; 0 claims a new slug. */
|
|
136
|
+
expectedVersion?: number;
|
|
137
|
+
uploadId?: string;
|
|
138
|
+
content?: string;
|
|
139
|
+
files?: InlineFile[];
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
export type UpdateReportInput = Pick<
|
|
143
|
+
PublishReportInput,
|
|
144
|
+
| "uploadId"
|
|
145
|
+
| "content"
|
|
146
|
+
| "files"
|
|
147
|
+
| "title"
|
|
148
|
+
| "description"
|
|
149
|
+
| "sourceTool"
|
|
150
|
+
| "sourceModel"
|
|
151
|
+
| "changeSummary"
|
|
152
|
+
| "expectedVersion"
|
|
153
|
+
>;
|
|
154
|
+
|
|
155
|
+
export interface ReportData {
|
|
156
|
+
id: string;
|
|
157
|
+
slug: string;
|
|
158
|
+
title: string;
|
|
159
|
+
url: string;
|
|
160
|
+
status: string;
|
|
161
|
+
currentVersion: number | null;
|
|
162
|
+
[key: string]: unknown;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* A publish held by a policy rule answers 202 with this instead of going live.
|
|
167
|
+
* `status` says which happened, so a caller that ignores it still gets a
|
|
168
|
+
* report object and a caller that reads it knows nobody can see the thing yet.
|
|
169
|
+
*/
|
|
170
|
+
export interface PublishResult {
|
|
171
|
+
status?: "published" | "updated" | "pending_approval";
|
|
172
|
+
report: ReportData;
|
|
173
|
+
version?: { id: string; versionNumber: number; [key: string]: unknown };
|
|
174
|
+
approval?: { id: string; status: string };
|
|
175
|
+
warnings?: string[];
|
|
176
|
+
[key: string]: unknown;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/* ── Comments ────────────────────────────────────────────────────────────── */
|
|
180
|
+
|
|
181
|
+
export interface CommentThread {
|
|
182
|
+
threadId: string;
|
|
183
|
+
status: "open" | "resolved";
|
|
184
|
+
quote: string | null;
|
|
185
|
+
messages: { author: string; authorType: string; body: string; createdAt: string }[];
|
|
186
|
+
[key: string]: unknown;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/* ── Webhooks ────────────────────────────────────────────────────────────── */
|
|
190
|
+
|
|
191
|
+
export type WebhookEventName =
|
|
192
|
+
| "report.published"
|
|
193
|
+
| "report.updated"
|
|
194
|
+
| "report.shared"
|
|
195
|
+
| "report.viewed"
|
|
196
|
+
| "comment.created"
|
|
197
|
+
| "access.requested"
|
|
198
|
+
| "schedule.due"
|
|
199
|
+
| "publish.held"
|
|
200
|
+
| "approval.requested"
|
|
201
|
+
| "approval.approved"
|
|
202
|
+
| "approval.rejected"
|
|
203
|
+
| "approval.expired"
|
|
204
|
+
| "approval.question"
|
|
205
|
+
| "approval.answered";
|
|
206
|
+
|
|
207
|
+
export interface WebhookEvent {
|
|
208
|
+
event: WebhookEventName;
|
|
209
|
+
sentAt: string;
|
|
210
|
+
/** Present and true when sent by the Send test button, not by real activity. */
|
|
211
|
+
test?: boolean;
|
|
212
|
+
data: Record<string, unknown>;
|
|
213
|
+
}
|
package/src/webhooks.ts
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import { createHmac, timingSafeEqual } from "node:crypto";
|
|
2
|
+
import { DeliverdError } from "./errors.js";
|
|
3
|
+
import type { WebhookEvent } from "./types.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Verifying what Deliverd sends you.
|
|
7
|
+
*
|
|
8
|
+
* The scheme is Stripe's — a timestamp and a signature in one header, the
|
|
9
|
+
* timestamp inside the signed material — so this is the verification everyone
|
|
10
|
+
* has written before. It is here anyway because a receiver that skips it is
|
|
11
|
+
* accepting anything anyone posts at the URL, and "write your own HMAC check"
|
|
12
|
+
* is the step every integration guide shows and half of them get wrong.
|
|
13
|
+
*
|
|
14
|
+
* Kept byte-for-byte with the server's own `lib/webhooks/signature.ts`;
|
|
15
|
+
* `sdk-parity.test.ts` on the server holds the two together.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
export const SIGNATURE_HEADER = "deliverd-signature";
|
|
19
|
+
export const EVENT_HEADER = "deliverd-event";
|
|
20
|
+
export const DELIVERY_HEADER = "deliverd-delivery";
|
|
21
|
+
|
|
22
|
+
/** How old a signature may be. Five minutes, as the server sends. */
|
|
23
|
+
export const TOLERANCE_SECONDS = 300;
|
|
24
|
+
|
|
25
|
+
export function signedPayload(timestamp: number, body: string): string {
|
|
26
|
+
return `${timestamp}.${body}`;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Whether the header is this secret's signature over this body, recently.
|
|
31
|
+
*
|
|
32
|
+
* `body` must be the raw request body, before any JSON parsing — a re-encoded
|
|
33
|
+
* object is a different string and will never verify. In Express that means
|
|
34
|
+
* `express.raw({ type: "application/json" })`; in Next.js `await request.text()`.
|
|
35
|
+
*/
|
|
36
|
+
export function verifySignature(
|
|
37
|
+
secret: string,
|
|
38
|
+
body: string,
|
|
39
|
+
header: string | null | undefined,
|
|
40
|
+
options: { now?: number; toleranceSeconds?: number } = {}
|
|
41
|
+
): boolean {
|
|
42
|
+
if (!header) return false;
|
|
43
|
+
const now = options.now ?? Math.floor(Date.now() / 1000);
|
|
44
|
+
const tolerance = options.toleranceSeconds ?? TOLERANCE_SECONDS;
|
|
45
|
+
|
|
46
|
+
const parts = new Map(
|
|
47
|
+
header.split(",").map((p) => {
|
|
48
|
+
const at = p.indexOf("=");
|
|
49
|
+
return [p.slice(0, at).trim(), p.slice(at + 1).trim()] as const;
|
|
50
|
+
})
|
|
51
|
+
);
|
|
52
|
+
const t = Number(parts.get("t"));
|
|
53
|
+
const v1 = parts.get("v1");
|
|
54
|
+
if (!Number.isFinite(t) || !v1) return false;
|
|
55
|
+
if (Math.abs(now - t) > tolerance) return false;
|
|
56
|
+
|
|
57
|
+
const expected = createHmac("sha256", secret).update(signedPayload(t, body)).digest("hex");
|
|
58
|
+
const a = Buffer.from(expected, "utf8");
|
|
59
|
+
const b = Buffer.from(v1, "utf8");
|
|
60
|
+
// Length first: timingSafeEqual throws on a mismatch, which leaks length.
|
|
61
|
+
if (a.length !== b.length) return false;
|
|
62
|
+
return timingSafeEqual(a, b);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Verify and parse in one step, the way a handler wants it.
|
|
67
|
+
*
|
|
68
|
+
* Throws rather than returning null, because a webhook route that treats an
|
|
69
|
+
* unverifiable body as "no event" answers 200 and tells the sender everything
|
|
70
|
+
* is fine.
|
|
71
|
+
*/
|
|
72
|
+
export function constructEvent(
|
|
73
|
+
secret: string,
|
|
74
|
+
body: string,
|
|
75
|
+
header: string | null | undefined,
|
|
76
|
+
options: { now?: number; toleranceSeconds?: number } = {}
|
|
77
|
+
): WebhookEvent {
|
|
78
|
+
if (!verifySignature(secret, body, header, options)) {
|
|
79
|
+
throw new DeliverdError(
|
|
80
|
+
400,
|
|
81
|
+
"invalid_signature",
|
|
82
|
+
"The signature did not verify. Check the endpoint's secret, and that you passed the raw request body rather than a re-encoded object."
|
|
83
|
+
);
|
|
84
|
+
}
|
|
85
|
+
try {
|
|
86
|
+
return JSON.parse(body) as WebhookEvent;
|
|
87
|
+
} catch (cause) {
|
|
88
|
+
throw new DeliverdError(400, "invalid_json", "The body verified but is not JSON.", undefined, { cause });
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
export class Webhooks {
|
|
93
|
+
verifySignature = verifySignature;
|
|
94
|
+
constructEvent = constructEvent;
|
|
95
|
+
readonly signatureHeader = SIGNATURE_HEADER;
|
|
96
|
+
readonly eventHeader = EVENT_HEADER;
|
|
97
|
+
readonly deliveryHeader = DELIVERY_HEADER;
|
|
98
|
+
}
|