@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/dist/index.js
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import { HttpClient } from "./http.js";
|
|
2
|
+
import { Approvals, FAST_POLL_SCHEDULE } from "./approvals.js";
|
|
3
|
+
import { Comments, Reports } from "./reports.js";
|
|
4
|
+
import { Webhooks } from "./webhooks.js";
|
|
5
|
+
import { developmentFetch } from "./dev.js";
|
|
6
|
+
import { durationMs } from "./duration.js";
|
|
7
|
+
export { Approval, Approvals, POLL_SCHEDULE } from "./approvals.js";
|
|
8
|
+
export { Comments, Reports } from "./reports.js";
|
|
9
|
+
export { constructEvent, DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER, TOLERANCE_SECONDS, verifySignature, Webhooks, } from "./webhooks.js";
|
|
10
|
+
export { DeliverdError, DeliverdTimeoutError } from "./errors.js";
|
|
11
|
+
export { DEFAULT_BASE_URL } from "./http.js";
|
|
12
|
+
export { durationMs } from "./duration.js";
|
|
13
|
+
/** How long a request waits for a person before it expires, unless you say. */
|
|
14
|
+
export const DEFAULT_EXPIRY = "24h";
|
|
15
|
+
/**
|
|
16
|
+
* Deliverd: you build the action, Deliverd handles the human.
|
|
17
|
+
*
|
|
18
|
+
* ```ts
|
|
19
|
+
* import { deliverd } from "@deliverd/sdk";
|
|
20
|
+
*
|
|
21
|
+
* const decision = await deliverd.approve({ title: "Deploy to production" });
|
|
22
|
+
* if (decision.approved) await deploy();
|
|
23
|
+
* ```
|
|
24
|
+
*
|
|
25
|
+
* That is the whole integration. What it stands in for: an approval page, the
|
|
26
|
+
* emails and the reminders, identity and single sign-on, who is allowed to
|
|
27
|
+
* decide, a table to keep it in, an audit trail, and the dashboard somebody
|
|
28
|
+
* uses to do it. None of that is yours to build.
|
|
29
|
+
*
|
|
30
|
+
* With no arguments the key comes from `DELIVERD_API_KEY`. Before you have
|
|
31
|
+
* one, `new Deliverd({ mode: "development" })` runs the same code with an
|
|
32
|
+
* imaginary approver.
|
|
33
|
+
*/
|
|
34
|
+
export class Deliverd {
|
|
35
|
+
approvals;
|
|
36
|
+
reports;
|
|
37
|
+
comments;
|
|
38
|
+
webhooks;
|
|
39
|
+
http;
|
|
40
|
+
/** Whether an imaginary approver is deciding these. */
|
|
41
|
+
development;
|
|
42
|
+
constructor(options = {}) {
|
|
43
|
+
const mode = options.mode ?? (process.env.DELIVERD_MODE === "development" ? "development" : "live");
|
|
44
|
+
this.development = mode === "development";
|
|
45
|
+
this.http = new HttpClient({
|
|
46
|
+
...options,
|
|
47
|
+
// A key is not needed when nothing leaves the machine.
|
|
48
|
+
apiKey: options.apiKey ?? process.env.DELIVERD_API_KEY ?? (this.development ? "dlv_development" : ""),
|
|
49
|
+
baseUrl: options.baseUrl ?? process.env.DELIVERD_BASE_URL,
|
|
50
|
+
fetch: this.development ? developmentFetch(options.development) : options.fetch,
|
|
51
|
+
});
|
|
52
|
+
this.approvals = new Approvals(this.http);
|
|
53
|
+
this.reports = new Reports(this.http);
|
|
54
|
+
this.comments = new Comments(this.http);
|
|
55
|
+
this.webhooks = new Webhooks();
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Ask a person, and wait for the answer.
|
|
59
|
+
*
|
|
60
|
+
* Resolves when they decide — including when they say no, because a refusal
|
|
61
|
+
* is an answer and `if (decision.approved)` is the line that follows. It
|
|
62
|
+
* throws only when the wait itself failed: a timeout, an abort, or an API
|
|
63
|
+
* that could not be reached.
|
|
64
|
+
*
|
|
65
|
+
* Requests expire after a day unless you say otherwise, so a wait always
|
|
66
|
+
* ends.
|
|
67
|
+
*/
|
|
68
|
+
async approve(options) {
|
|
69
|
+
const { expiresIn, timeout, onQuestion, onPoll, signal, reuse, ...input } = options;
|
|
70
|
+
if (input.externalId && reuse !== false) {
|
|
71
|
+
const existing = await this.approvals.findByExternalId(input.externalId, signal);
|
|
72
|
+
if (existing) {
|
|
73
|
+
const settled = await existing.wait({
|
|
74
|
+
onQuestion,
|
|
75
|
+
onPoll,
|
|
76
|
+
signal,
|
|
77
|
+
timeout: durationOrUndefined(timeout),
|
|
78
|
+
...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
|
|
79
|
+
});
|
|
80
|
+
return settled.toDecision();
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
const approval = await this.approvals.create({
|
|
84
|
+
...input,
|
|
85
|
+
expiresAt: options.expiresAt ?? new Date(Date.now() + durationMs(expiresIn ?? DEFAULT_EXPIRY)).toISOString(),
|
|
86
|
+
}, signal);
|
|
87
|
+
const settled = await approval.wait({
|
|
88
|
+
onQuestion,
|
|
89
|
+
onPoll,
|
|
90
|
+
signal,
|
|
91
|
+
/*
|
|
92
|
+
* In development the approver is imaginary and instant, so a wait still
|
|
93
|
+
* running after a moment is a path that will never settle — a question
|
|
94
|
+
* with nothing to answer it, usually. Ending it quickly turns that into
|
|
95
|
+
* a message; leaving it turns it into a hung test suite. Two seconds
|
|
96
|
+
* rather than five, because five is what a test runner gives a whole
|
|
97
|
+
* test and losing the race to it reports the wrong failure.
|
|
98
|
+
*/
|
|
99
|
+
timeout: durationOrUndefined(timeout) ?? (this.development ? 2_000 : undefined),
|
|
100
|
+
...(this.development ? { pollIntervals: FAST_POLL_SCHEDULE } : {}),
|
|
101
|
+
});
|
|
102
|
+
return settled.toDecision();
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* A yes or no on something small: same mechanism, lower ceremony.
|
|
106
|
+
*
|
|
107
|
+
* Low risk and an hour to answer, because that is what "are you sure?"
|
|
108
|
+
* means — if it deserves a day and a paragraph of evidence, it deserves
|
|
109
|
+
* `approve()`.
|
|
110
|
+
*/
|
|
111
|
+
async confirm(options) {
|
|
112
|
+
const decision = await this.approve({ risk: "low", expiresIn: "1h", ...options });
|
|
113
|
+
return decision.approved;
|
|
114
|
+
}
|
|
115
|
+
/** Publish HTML to a secure URL. The other half of the product, one call in. */
|
|
116
|
+
publish(input, signal) {
|
|
117
|
+
return this.reports.publish(input, signal);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
function durationOrUndefined(value) {
|
|
121
|
+
return value === undefined ? undefined : durationMs(value);
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* A client that builds itself from the environment the first time you touch
|
|
125
|
+
* it, so the shortest integration has no setup line at all:
|
|
126
|
+
*
|
|
127
|
+
* ```ts
|
|
128
|
+
* import { deliverd } from "@deliverd/sdk";
|
|
129
|
+
* await deliverd.approve({ title: "Deploy production" });
|
|
130
|
+
* ```
|
|
131
|
+
*
|
|
132
|
+
* Lazy rather than eager: a module that threw at import time because an
|
|
133
|
+
* environment variable was missing would take a whole process down for a call
|
|
134
|
+
* nobody made yet.
|
|
135
|
+
*/
|
|
136
|
+
let singleton;
|
|
137
|
+
export const deliverd = new Proxy({}, {
|
|
138
|
+
get(_target, property, receiver) {
|
|
139
|
+
singleton ??= new Deliverd();
|
|
140
|
+
const value = Reflect.get(singleton, property, singleton);
|
|
141
|
+
return typeof value === "function" ? value.bind(singleton) : value;
|
|
142
|
+
},
|
|
143
|
+
});
|
|
144
|
+
export default Deliverd;
|
|
@@ -0,0 +1,24 @@
|
|
|
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
|
+
export interface Explanation {
|
|
13
|
+
/** Replaces the API's message when we can say it better. */
|
|
14
|
+
message?: string;
|
|
15
|
+
/** The line under it: what to do. */
|
|
16
|
+
hint: string;
|
|
17
|
+
}
|
|
18
|
+
export declare const EXPLANATIONS: Record<string, Explanation>;
|
|
19
|
+
/** The message as a developer should read it: what happened, then what to do. */
|
|
20
|
+
export declare function explain(code: string, apiMessage: string): {
|
|
21
|
+
message: string;
|
|
22
|
+
hint?: string;
|
|
23
|
+
};
|
|
24
|
+
//# sourceMappingURL=messages.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAmDpD,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAI5F"}
|
package/dist/messages.js
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
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
|
+
export const EXPLANATIONS = {
|
|
13
|
+
no_api_key: {
|
|
14
|
+
message: "No API key.",
|
|
15
|
+
hint: "Set DELIVERD_API_KEY in your environment, or pass { apiKey } — or use { mode: \"development\" } to run without one.",
|
|
16
|
+
},
|
|
17
|
+
auth_error: {
|
|
18
|
+
message: "That API key was not accepted.",
|
|
19
|
+
hint: "Check DELIVERD_API_KEY. Keys start with dlv_ and are created in Settings → API tokens.",
|
|
20
|
+
},
|
|
21
|
+
insufficient_scope: {
|
|
22
|
+
hint: "Reissue the key with the scope named above. A key issued before a scope existed does not have it.",
|
|
23
|
+
},
|
|
24
|
+
unknown_approver: {
|
|
25
|
+
message: "No approver could be found for this request.",
|
|
26
|
+
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.",
|
|
27
|
+
},
|
|
28
|
+
self_approval: {
|
|
29
|
+
message: "You cannot approve your own request.",
|
|
30
|
+
hint: "Name somebody else in `approvers`, or leave it out so your organisation's owners and admins decide.",
|
|
31
|
+
},
|
|
32
|
+
not_approver: {
|
|
33
|
+
hint: "Only the people named on the request can decide it.",
|
|
34
|
+
},
|
|
35
|
+
not_requester: {
|
|
36
|
+
message: "Only the requester can answer a question on their own request.",
|
|
37
|
+
hint: "Use the same key that created the approval.",
|
|
38
|
+
},
|
|
39
|
+
not_pending: {
|
|
40
|
+
message: "That request was already decided.",
|
|
41
|
+
hint: "Read its status rather than deciding again; a decision is final.",
|
|
42
|
+
},
|
|
43
|
+
expired: {
|
|
44
|
+
message: "That request expired before anyone decided it.",
|
|
45
|
+
hint: "Ask again, with a longer `expiresIn`, or chase the approver.",
|
|
46
|
+
},
|
|
47
|
+
rate_limited: {
|
|
48
|
+
message: "Too many requests.",
|
|
49
|
+
hint: "The SDK already retried and gave up. Reduce how often you poll, or wait with `approve()` rather than looping yourself.",
|
|
50
|
+
},
|
|
51
|
+
plan_limit: {
|
|
52
|
+
hint: "Your organisation's plan does not include this. Billing → Plans.",
|
|
53
|
+
},
|
|
54
|
+
network_error: {
|
|
55
|
+
hint: "Check the machine's network and `baseUrl`. Deliverd's status is at https://deliverd.dev.",
|
|
56
|
+
},
|
|
57
|
+
timeout: {
|
|
58
|
+
hint: "Nobody decided in time. The request is still open at the URL above until it expires.",
|
|
59
|
+
},
|
|
60
|
+
invalid_signature: {
|
|
61
|
+
hint: "Check the endpoint's signing secret, and that you passed the raw request body rather than a re-encoded object.",
|
|
62
|
+
},
|
|
63
|
+
};
|
|
64
|
+
/** The message as a developer should read it: what happened, then what to do. */
|
|
65
|
+
export function explain(code, apiMessage) {
|
|
66
|
+
const found = EXPLANATIONS[code];
|
|
67
|
+
if (!found)
|
|
68
|
+
return { message: apiMessage };
|
|
69
|
+
return { message: `${found.message ?? apiMessage}\n${found.hint}`, hint: found.hint };
|
|
70
|
+
}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import type { HttpClient } from "./http.js";
|
|
2
|
+
import type { CommentThread, PublishReportInput, PublishResult, ReportData, UpdateReportInput } from "./types.js";
|
|
3
|
+
/**
|
|
4
|
+
* The publishing half: get what the agent wrote to the people who need it, at
|
|
5
|
+
* an address that does not change.
|
|
6
|
+
*
|
|
7
|
+
* Thin on purpose. These are the REST routes with their names spelled the way
|
|
8
|
+
* a person would say them, and nothing else — the service decides what a
|
|
9
|
+
* publish means, and an SDK that reimplemented any of it would be a second
|
|
10
|
+
* answer to the same question.
|
|
11
|
+
*/
|
|
12
|
+
export declare class Reports {
|
|
13
|
+
private readonly http;
|
|
14
|
+
constructor(http: HttpClient);
|
|
15
|
+
/**
|
|
16
|
+
* Publish HTML to a secure URL.
|
|
17
|
+
*
|
|
18
|
+
* Check `result.status`: a publishing policy can hold the version for a
|
|
19
|
+
* person's approval, in which case nothing is live yet and `result.approval`
|
|
20
|
+
* names the request.
|
|
21
|
+
*/
|
|
22
|
+
publish(input: PublishReportInput, signal?: AbortSignal): Promise<PublishResult>;
|
|
23
|
+
/** A new version of an existing report, keeping its URL and its audience. */
|
|
24
|
+
update(idOrSlug: string, input: UpdateReportInput, signal?: AbortSignal): Promise<PublishResult>;
|
|
25
|
+
get(idOrSlug: string, signal?: AbortSignal): Promise<ReportData>;
|
|
26
|
+
list(query?: string, signal?: AbortSignal): Promise<ReportData[]>;
|
|
27
|
+
/** Change the title, the address, or both. The old address keeps working. */
|
|
28
|
+
rename(idOrSlug: string, input: {
|
|
29
|
+
title?: string;
|
|
30
|
+
slug?: string;
|
|
31
|
+
description?: string;
|
|
32
|
+
workspaceId?: string;
|
|
33
|
+
}, signal?: AbortSignal): Promise<ReportData>;
|
|
34
|
+
/** Grant people, teams or groups access. Filing is not access; this is. */
|
|
35
|
+
share(idOrSlug: string, audience: unknown, signal?: AbortSignal): Promise<unknown[]>;
|
|
36
|
+
/** Stop the URL serving. `archived: false` puts it back. */
|
|
37
|
+
archive(idOrSlug: string, archived?: boolean, signal?: AbortSignal): Promise<ReportData>;
|
|
38
|
+
rollback(idOrSlug: string, version: number, signal?: AbortSignal): Promise<unknown>;
|
|
39
|
+
/**
|
|
40
|
+
* Every version, with `latestVersion` beside `currentVersion`. Pass
|
|
41
|
+
* `latestVersion` as `expectedVersion` on an update: a held or declined
|
|
42
|
+
* version takes a number without going live.
|
|
43
|
+
*/
|
|
44
|
+
versions(idOrSlug: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
|
|
45
|
+
/** Who read it and when. The detail needs the analytics plan. */
|
|
46
|
+
analytics(idOrSlug: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
|
|
47
|
+
/** Replace a dataset a living report reads. No new version, same URL. */
|
|
48
|
+
putData(idOrSlug: string, name: string, data: unknown, signal?: AbortSignal): Promise<unknown>;
|
|
49
|
+
listData(idOrSlug: string, signal?: AbortSignal): Promise<unknown>;
|
|
50
|
+
/**
|
|
51
|
+
* The open feedback composed into one prompt, with the readers' images as
|
|
52
|
+
* signed links: everything needed to write the next version.
|
|
53
|
+
*/
|
|
54
|
+
revisionBrief(idOrSlug: string, input?: {
|
|
55
|
+
threadIds?: string[];
|
|
56
|
+
instructions?: string;
|
|
57
|
+
}, signal?: AbortSignal): Promise<Record<string, unknown>>;
|
|
58
|
+
}
|
|
59
|
+
/** Reader feedback, anchored to the passage it is about. */
|
|
60
|
+
export declare class Comments {
|
|
61
|
+
private readonly http;
|
|
62
|
+
constructor(http: HttpClient);
|
|
63
|
+
list(idOrSlug: string, status?: "open" | "resolved" | "all", signal?: AbortSignal): Promise<CommentThread[]>;
|
|
64
|
+
/** `quote` anchors it to a passage; `threadId` replies to one. */
|
|
65
|
+
create(idOrSlug: string, input: {
|
|
66
|
+
body: string;
|
|
67
|
+
quote?: string;
|
|
68
|
+
threadId?: string;
|
|
69
|
+
}, signal?: AbortSignal): Promise<unknown>;
|
|
70
|
+
/** Mark a thread resolved, with a note on what changed. */
|
|
71
|
+
resolve(threadId: string, input?: {
|
|
72
|
+
note?: string;
|
|
73
|
+
reopen?: boolean;
|
|
74
|
+
}, signal?: AbortSignal): Promise<unknown>;
|
|
75
|
+
}
|
|
76
|
+
//# sourceMappingURL=reports.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"reports.d.ts","sourceRoot":"","sources":["../src/reports.ts"],"names":[],"mappings":"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"}
|
package/dist/reports.js
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The publishing half: get what the agent wrote to the people who need it, at
|
|
3
|
+
* an address that does not change.
|
|
4
|
+
*
|
|
5
|
+
* Thin on purpose. These are the REST routes with their names spelled the way
|
|
6
|
+
* a person would say them, and nothing else — the service decides what a
|
|
7
|
+
* publish means, and an SDK that reimplemented any of it would be a second
|
|
8
|
+
* answer to the same question.
|
|
9
|
+
*/
|
|
10
|
+
export class Reports {
|
|
11
|
+
http;
|
|
12
|
+
constructor(http) {
|
|
13
|
+
this.http = http;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Publish HTML to a secure URL.
|
|
17
|
+
*
|
|
18
|
+
* Check `result.status`: a publishing policy can hold the version for a
|
|
19
|
+
* person's approval, in which case nothing is live yet and `result.approval`
|
|
20
|
+
* names the request.
|
|
21
|
+
*/
|
|
22
|
+
publish(input, signal) {
|
|
23
|
+
return this.http.request({ method: "POST", path: "/reports", body: input, signal });
|
|
24
|
+
}
|
|
25
|
+
/** A new version of an existing report, keeping its URL and its audience. */
|
|
26
|
+
update(idOrSlug, input, signal) {
|
|
27
|
+
return this.http.request({
|
|
28
|
+
method: "POST",
|
|
29
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/versions`,
|
|
30
|
+
body: input,
|
|
31
|
+
signal,
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
get(idOrSlug, signal) {
|
|
35
|
+
return this.http.request({
|
|
36
|
+
method: "GET",
|
|
37
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}`,
|
|
38
|
+
signal,
|
|
39
|
+
});
|
|
40
|
+
}
|
|
41
|
+
async list(query, signal) {
|
|
42
|
+
const { reports } = await this.http.request({
|
|
43
|
+
method: "GET",
|
|
44
|
+
path: "/reports",
|
|
45
|
+
query: { q: query },
|
|
46
|
+
signal,
|
|
47
|
+
});
|
|
48
|
+
return reports;
|
|
49
|
+
}
|
|
50
|
+
/** Change the title, the address, or both. The old address keeps working. */
|
|
51
|
+
rename(idOrSlug, input, signal) {
|
|
52
|
+
return this.http.request({
|
|
53
|
+
method: "PATCH",
|
|
54
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}`,
|
|
55
|
+
body: input,
|
|
56
|
+
signal,
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
/** Grant people, teams or groups access. Filing is not access; this is. */
|
|
60
|
+
async share(idOrSlug, audience, signal) {
|
|
61
|
+
const { granted } = await this.http.request({
|
|
62
|
+
method: "POST",
|
|
63
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/share`,
|
|
64
|
+
body: { audience },
|
|
65
|
+
signal,
|
|
66
|
+
});
|
|
67
|
+
return granted;
|
|
68
|
+
}
|
|
69
|
+
/** Stop the URL serving. `archived: false` puts it back. */
|
|
70
|
+
archive(idOrSlug, archived = true, signal) {
|
|
71
|
+
return this.http.request({
|
|
72
|
+
method: "POST",
|
|
73
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/archive`,
|
|
74
|
+
body: { archived },
|
|
75
|
+
signal,
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
rollback(idOrSlug, version, signal) {
|
|
79
|
+
return this.http.request({
|
|
80
|
+
method: "POST",
|
|
81
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/rollback`,
|
|
82
|
+
body: { version },
|
|
83
|
+
signal,
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Every version, with `latestVersion` beside `currentVersion`. Pass
|
|
88
|
+
* `latestVersion` as `expectedVersion` on an update: a held or declined
|
|
89
|
+
* version takes a number without going live.
|
|
90
|
+
*/
|
|
91
|
+
versions(idOrSlug, signal) {
|
|
92
|
+
return this.http.request({
|
|
93
|
+
method: "GET",
|
|
94
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/versions`,
|
|
95
|
+
signal,
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
/** Who read it and when. The detail needs the analytics plan. */
|
|
99
|
+
analytics(idOrSlug, signal) {
|
|
100
|
+
return this.http.request({
|
|
101
|
+
method: "GET",
|
|
102
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/analytics`,
|
|
103
|
+
signal,
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
/** Replace a dataset a living report reads. No new version, same URL. */
|
|
107
|
+
putData(idOrSlug, name, data, signal) {
|
|
108
|
+
return this.http.request({
|
|
109
|
+
method: "PUT",
|
|
110
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/data/${encodeURIComponent(name)}`,
|
|
111
|
+
body: data,
|
|
112
|
+
signal,
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
listData(idOrSlug, signal) {
|
|
116
|
+
return this.http.request({
|
|
117
|
+
method: "GET",
|
|
118
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/data`,
|
|
119
|
+
signal,
|
|
120
|
+
});
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* The open feedback composed into one prompt, with the readers' images as
|
|
124
|
+
* signed links: everything needed to write the next version.
|
|
125
|
+
*/
|
|
126
|
+
revisionBrief(idOrSlug, input = {}, signal) {
|
|
127
|
+
return this.http.request({
|
|
128
|
+
method: "POST",
|
|
129
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/revision-briefs`,
|
|
130
|
+
body: input,
|
|
131
|
+
signal,
|
|
132
|
+
});
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
/** Reader feedback, anchored to the passage it is about. */
|
|
136
|
+
export class Comments {
|
|
137
|
+
http;
|
|
138
|
+
constructor(http) {
|
|
139
|
+
this.http = http;
|
|
140
|
+
}
|
|
141
|
+
async list(idOrSlug, status = "open", signal) {
|
|
142
|
+
const { threads } = await this.http.request({
|
|
143
|
+
method: "GET",
|
|
144
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/comments`,
|
|
145
|
+
query: { status },
|
|
146
|
+
signal,
|
|
147
|
+
});
|
|
148
|
+
return threads;
|
|
149
|
+
}
|
|
150
|
+
/** `quote` anchors it to a passage; `threadId` replies to one. */
|
|
151
|
+
create(idOrSlug, input, signal) {
|
|
152
|
+
return this.http.request({
|
|
153
|
+
method: "POST",
|
|
154
|
+
path: `/reports/${encodeURIComponent(idOrSlug)}/comments`,
|
|
155
|
+
body: input,
|
|
156
|
+
signal,
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
/** Mark a thread resolved, with a note on what changed. */
|
|
160
|
+
resolve(threadId, input = {}, signal) {
|
|
161
|
+
return this.http.request({
|
|
162
|
+
method: "POST",
|
|
163
|
+
path: `/comments/${encodeURIComponent(threadId)}/resolve`,
|
|
164
|
+
body: input,
|
|
165
|
+
signal,
|
|
166
|
+
});
|
|
167
|
+
}
|
|
168
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
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
|
+
export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled";
|
|
12
|
+
export type ApprovalRisk = "low" | "medium" | "high" | "critical";
|
|
13
|
+
/** One line of evidence, as the approval page shows it. */
|
|
14
|
+
export interface ApprovalFactor {
|
|
15
|
+
label: string;
|
|
16
|
+
status?: "ok" | "warning" | "info";
|
|
17
|
+
detail?: string;
|
|
18
|
+
}
|
|
19
|
+
export interface ApprovalLink {
|
|
20
|
+
label: string;
|
|
21
|
+
url: string;
|
|
22
|
+
}
|
|
23
|
+
export interface ApprovalQuestion {
|
|
24
|
+
id: string;
|
|
25
|
+
question: string;
|
|
26
|
+
answer: string | null;
|
|
27
|
+
askedAt: string;
|
|
28
|
+
answeredAt: string | null;
|
|
29
|
+
}
|
|
30
|
+
export interface ApprovalData {
|
|
31
|
+
id: string;
|
|
32
|
+
status: ApprovalStatus;
|
|
33
|
+
/** The page the approver decides on. */
|
|
34
|
+
url: string;
|
|
35
|
+
title: string;
|
|
36
|
+
description: string | null;
|
|
37
|
+
risk: ApprovalRisk;
|
|
38
|
+
factors: ApprovalFactor[];
|
|
39
|
+
links: ApprovalLink[];
|
|
40
|
+
reportId: string | null;
|
|
41
|
+
externalId: string | null;
|
|
42
|
+
metadata: Record<string, unknown>;
|
|
43
|
+
requestedBy: string;
|
|
44
|
+
approvers: string[];
|
|
45
|
+
decidedBy: string | null;
|
|
46
|
+
decidedAt: string | null;
|
|
47
|
+
/** The approver's reason, on a rejection or an approval that carried one. */
|
|
48
|
+
note: string | null;
|
|
49
|
+
expiresAt: string | null;
|
|
50
|
+
questions: ApprovalQuestion[];
|
|
51
|
+
createdAt: string;
|
|
52
|
+
}
|
|
53
|
+
export interface CreateApprovalInput {
|
|
54
|
+
/** What is being asked, as a headline. */
|
|
55
|
+
title: string;
|
|
56
|
+
/** Why, what it affects, what it costs — what the approver reads first. */
|
|
57
|
+
description?: string;
|
|
58
|
+
/** How the approver should weigh it. Medium when omitted. */
|
|
59
|
+
risk?: ApprovalRisk;
|
|
60
|
+
/** Evidence, one line each, shown as a checklist. */
|
|
61
|
+
factors?: ApprovalFactor[];
|
|
62
|
+
/** Where to read more. */
|
|
63
|
+
links?: ApprovalLink[];
|
|
64
|
+
/** A published report the request is about. */
|
|
65
|
+
reportId?: string;
|
|
66
|
+
/**
|
|
67
|
+
* Emails or user ids of members who may decide. The organisation's owners
|
|
68
|
+
* and admins when omitted. You cannot name yourself.
|
|
69
|
+
*/
|
|
70
|
+
approvers?: string[];
|
|
71
|
+
/** After this the request expires undecided. ISO 8601. */
|
|
72
|
+
expiresAt?: string;
|
|
73
|
+
/** Your own reference, returned unchanged and searchable. */
|
|
74
|
+
externalId?: string;
|
|
75
|
+
metadata?: Record<string, unknown>;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* The answer to `approve()`.
|
|
79
|
+
*
|
|
80
|
+
* Flat on purpose: the line after the call is `if (decision.approved)`, and
|
|
81
|
+
* anything a caller has to reach through to get there is a step this SDK
|
|
82
|
+
* exists to remove. The whole request is on `approval` when a field here does
|
|
83
|
+
* not cover it.
|
|
84
|
+
*/
|
|
85
|
+
export type Decision = {
|
|
86
|
+
/** True only for an approval. False for rejected, expired and cancelled. */
|
|
87
|
+
approved: boolean;
|
|
88
|
+
/** For a switch, and for narrowing. */
|
|
89
|
+
status: "approved" | "rejected" | "expired" | "cancelled";
|
|
90
|
+
/** Their reason, when they gave one. */
|
|
91
|
+
note: string | null;
|
|
92
|
+
decidedBy: string | null;
|
|
93
|
+
decidedAt: string | null;
|
|
94
|
+
id: string;
|
|
95
|
+
/** The page they decided on. Worth logging. */
|
|
96
|
+
url: string;
|
|
97
|
+
/** The request itself, for anything the fields above do not name. */
|
|
98
|
+
approval: unknown;
|
|
99
|
+
};
|
|
100
|
+
export interface ListApprovalsInput {
|
|
101
|
+
status?: ApprovalStatus;
|
|
102
|
+
externalId?: string;
|
|
103
|
+
limit?: number;
|
|
104
|
+
}
|
|
105
|
+
export interface InlineFile {
|
|
106
|
+
path: string;
|
|
107
|
+
content: string;
|
|
108
|
+
/** `base64` for an image or a font; text otherwise. */
|
|
109
|
+
encoding?: "utf8" | "base64";
|
|
110
|
+
}
|
|
111
|
+
export interface PublishReportInput {
|
|
112
|
+
title?: string;
|
|
113
|
+
slug?: string;
|
|
114
|
+
description?: string;
|
|
115
|
+
workspaceId?: string;
|
|
116
|
+
/** Names, teams, groups or emails — resolved server-side. */
|
|
117
|
+
audience?: unknown;
|
|
118
|
+
classification?: string;
|
|
119
|
+
living?: boolean;
|
|
120
|
+
sourceTool?: string;
|
|
121
|
+
sourceModel?: string;
|
|
122
|
+
changeSummary?: string;
|
|
123
|
+
/** Publish only if this is still the current version; 0 claims a new slug. */
|
|
124
|
+
expectedVersion?: number;
|
|
125
|
+
uploadId?: string;
|
|
126
|
+
content?: string;
|
|
127
|
+
files?: InlineFile[];
|
|
128
|
+
}
|
|
129
|
+
export type UpdateReportInput = Pick<PublishReportInput, "uploadId" | "content" | "files" | "title" | "description" | "sourceTool" | "sourceModel" | "changeSummary" | "expectedVersion">;
|
|
130
|
+
export interface ReportData {
|
|
131
|
+
id: string;
|
|
132
|
+
slug: string;
|
|
133
|
+
title: string;
|
|
134
|
+
url: string;
|
|
135
|
+
status: string;
|
|
136
|
+
currentVersion: number | null;
|
|
137
|
+
[key: string]: unknown;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* A publish held by a policy rule answers 202 with this instead of going live.
|
|
141
|
+
* `status` says which happened, so a caller that ignores it still gets a
|
|
142
|
+
* report object and a caller that reads it knows nobody can see the thing yet.
|
|
143
|
+
*/
|
|
144
|
+
export interface PublishResult {
|
|
145
|
+
status?: "published" | "updated" | "pending_approval";
|
|
146
|
+
report: ReportData;
|
|
147
|
+
version?: {
|
|
148
|
+
id: string;
|
|
149
|
+
versionNumber: number;
|
|
150
|
+
[key: string]: unknown;
|
|
151
|
+
};
|
|
152
|
+
approval?: {
|
|
153
|
+
id: string;
|
|
154
|
+
status: string;
|
|
155
|
+
};
|
|
156
|
+
warnings?: string[];
|
|
157
|
+
[key: string]: unknown;
|
|
158
|
+
}
|
|
159
|
+
export interface CommentThread {
|
|
160
|
+
threadId: string;
|
|
161
|
+
status: "open" | "resolved";
|
|
162
|
+
quote: string | null;
|
|
163
|
+
messages: {
|
|
164
|
+
author: string;
|
|
165
|
+
authorType: string;
|
|
166
|
+
body: string;
|
|
167
|
+
createdAt: string;
|
|
168
|
+
}[];
|
|
169
|
+
[key: string]: unknown;
|
|
170
|
+
}
|
|
171
|
+
export type WebhookEventName = "report.published" | "report.updated" | "report.shared" | "report.viewed" | "comment.created" | "access.requested" | "schedule.due" | "publish.held" | "approval.requested" | "approval.approved" | "approval.rejected" | "approval.expired" | "approval.question" | "approval.answered";
|
|
172
|
+
export interface WebhookEvent {
|
|
173
|
+
event: WebhookEventName;
|
|
174
|
+
sentAt: string;
|
|
175
|
+
/** Present and true when sent by the Send test button, not by real activity. */
|
|
176
|
+
test?: boolean;
|
|
177
|
+
data: Record<string, unknown>;
|
|
178
|
+
}
|
|
179
|
+
//# sourceMappingURL=types.d.ts.map
|