@proofline/sdk 4.0.0 → 5.0.1
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 +20 -1
- package/dist/index.d.ts +1 -1
- package/dist/schema.d.ts +7 -7
- package/dist/transport.d.ts +15 -1
- package/dist/transport.js +90 -9
- package/openapi.public.json +8 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -19,6 +19,25 @@ When no token is passed, the client reads `PROOFLINE_TOKEN`, keeps it in memory,
|
|
|
19
19
|
|
|
20
20
|
This repository is the published distribution of the Proofline TypeScript SDK. The public OpenAPI contract in `openapi.public.json` generates `src/operations.ts` and `src/schema.d.ts`. The transport in `src/transport.ts`, client helpers, and tests in `tests/` are hand-written. Open an [issue](https://github.com/prooflinedev/sdk-typescript/issues) for changes to the OpenAPI contract, generated code, or workflows. Pull requests are welcome for the hand-written parts.
|
|
21
21
|
|
|
22
|
+
## Errors and refusals
|
|
23
|
+
|
|
24
|
+
A refused request throws `ProoflineError` with the server problem's `status`, `type`, `title` and `detail`. When a review request creates nothing, the error also carries `refusal`, whose `reason` names the setting to change, such as `NO_LINKED_ENVIRONMENT` or `ENVIRONMENT_NOT_READY`, and `repositoryName`. A refusal that does not match the public contract keeps its status, `title` and `detail` with the type `urn:proofline:sdk:invalid-response` and no `refusal`. The token is redacted from every text field, and `String(error)`, `inspect(error)` and `JSON.stringify(error)` show only the status.
|
|
25
|
+
|
|
26
|
+
```typescript
|
|
27
|
+
import { ProoflineError } from "@proofline/sdk";
|
|
28
|
+
|
|
29
|
+
try {
|
|
30
|
+
await client.requestReview({
|
|
31
|
+
path: { org_id: organizationId, repo_id: repositoryId, number: 12 },
|
|
32
|
+
});
|
|
33
|
+
} catch (error) {
|
|
34
|
+
if (!(error instanceof ProoflineError) || error.refusal === undefined) throw error;
|
|
35
|
+
if (error.refusal.reason === "NO_LINKED_ENVIRONMENT")
|
|
36
|
+
console.error(`Link an environment to ${error.repositoryName}.`);
|
|
37
|
+
else console.error(error.detail);
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
22
41
|
## Coverage uploads
|
|
23
42
|
|
|
24
43
|
Upload CI coverage reports with a repository-restricted token that holds `coverage:write`. The token holder must have current GitHub write access to that repository. Set `PROOFLINE_TOKEN` to that token and pass the full commit SHA that the tests ran on. The server refuses branch names and abbreviated SHAs.
|
|
@@ -38,7 +57,7 @@ const report = await client.uploadCoverageReports(
|
|
|
38
57
|
console.log(report.report_id, report.created);
|
|
39
58
|
```
|
|
40
59
|
|
|
41
|
-
Send 1 to 50 LCOV, Cobertura XML, JaCoCo XML, or Go cover reports in a JSON body of at most
|
|
60
|
+
Send 1 to 50 LCOV, Cobertura XML, JaCoCo XML, or Go cover reports in a JSON body of at most 30 MiB. Each report name must be a unique relative path, and content must be the original report text. Repeating an identical upload returns the existing report with `created: false`. An upload receipt records evidence; it does not indicate that a coverage check is met.
|
|
42
61
|
|
|
43
62
|
## Review exports
|
|
44
63
|
|
package/dist/index.d.ts
CHANGED
|
@@ -11,7 +11,7 @@ import type { components } from "./schema.js";
|
|
|
11
11
|
import { type ClientOptions } from "./transport.js";
|
|
12
12
|
export type * from "./operations.js";
|
|
13
13
|
export type { components, operations, paths } from "./schema.js";
|
|
14
|
-
export type { ClientOptions } from "./transport.js";
|
|
14
|
+
export type { ClientOptions, ProblemFields, RunNowRefusal, } from "./transport.js";
|
|
15
15
|
export { ProoflineError, SecretToken } from "./transport.js";
|
|
16
16
|
export type Review = components["schemas"]["CustomerReviewDetail"];
|
|
17
17
|
export type Assessment = components["schemas"]["CustomerAssessment"];
|
package/dist/schema.d.ts
CHANGED
|
@@ -827,7 +827,7 @@ export interface components {
|
|
|
827
827
|
CoverageUploadRequest: {
|
|
828
828
|
/**
|
|
829
829
|
* @description One to 50 reports, each LCOV, Cobertura XML, `JaCoCo` XML or a Go
|
|
830
|
-
* cover profile, in a JSON body of at most
|
|
830
|
+
* cover profile, in a JSON body of at most 30 MiB.
|
|
831
831
|
*/
|
|
832
832
|
reports: components["schemas"]["UploadedReport"][];
|
|
833
833
|
/**
|
|
@@ -3710,7 +3710,7 @@ export interface operations {
|
|
|
3710
3710
|
[name: string]: unknown;
|
|
3711
3711
|
};
|
|
3712
3712
|
content: {
|
|
3713
|
-
"application/json": components["schemas"]["RunNowRefused"];
|
|
3713
|
+
"application/problem+json": components["schemas"]["RunNowRefused"];
|
|
3714
3714
|
};
|
|
3715
3715
|
};
|
|
3716
3716
|
/** @description An RFC 9457 problem; the HTTP status remains authoritative. */
|
|
@@ -3768,7 +3768,7 @@ export interface operations {
|
|
|
3768
3768
|
[name: string]: unknown;
|
|
3769
3769
|
};
|
|
3770
3770
|
content: {
|
|
3771
|
-
"application/json": components["schemas"]["CoverageRefused"];
|
|
3771
|
+
"application/problem+json": components["schemas"]["CoverageRefused"];
|
|
3772
3772
|
};
|
|
3773
3773
|
};
|
|
3774
3774
|
/** @description An RFC 9457 problem; the HTTP status remains authoritative. */
|
|
@@ -3823,7 +3823,7 @@ export interface operations {
|
|
|
3823
3823
|
[name: string]: unknown;
|
|
3824
3824
|
};
|
|
3825
3825
|
content: {
|
|
3826
|
-
"application/json": components["schemas"]["RunNowRefused"];
|
|
3826
|
+
"application/problem+json": components["schemas"]["RunNowRefused"];
|
|
3827
3827
|
};
|
|
3828
3828
|
};
|
|
3829
3829
|
/** @description An RFC 9457 problem; the HTTP status remains authoritative. */
|
|
@@ -3878,7 +3878,7 @@ export interface operations {
|
|
|
3878
3878
|
[name: string]: unknown;
|
|
3879
3879
|
};
|
|
3880
3880
|
content: {
|
|
3881
|
-
"application/json": components["schemas"]["RunNowRefused"];
|
|
3881
|
+
"application/problem+json": components["schemas"]["RunNowRefused"];
|
|
3882
3882
|
};
|
|
3883
3883
|
};
|
|
3884
3884
|
/** @description An RFC 9457 problem; the HTTP status remains authoritative. */
|
|
@@ -3937,7 +3937,7 @@ export interface operations {
|
|
|
3937
3937
|
[name: string]: unknown;
|
|
3938
3938
|
};
|
|
3939
3939
|
content: {
|
|
3940
|
-
"application/json": components["schemas"]["RunNowRefused"];
|
|
3940
|
+
"application/problem+json": components["schemas"]["RunNowRefused"];
|
|
3941
3941
|
};
|
|
3942
3942
|
};
|
|
3943
3943
|
/** @description An RFC 9457 problem; the HTTP status remains authoritative. */
|
|
@@ -4023,7 +4023,7 @@ export interface operations {
|
|
|
4023
4023
|
[name: string]: unknown;
|
|
4024
4024
|
};
|
|
4025
4025
|
content: {
|
|
4026
|
-
"application/json": components["schemas"]["RunNowRefused"];
|
|
4026
|
+
"application/problem+json": components["schemas"]["RunNowRefused"];
|
|
4027
4027
|
};
|
|
4028
4028
|
};
|
|
4029
4029
|
/** @description An RFC 9457 problem; the HTTP status remains authoritative. */
|
package/dist/transport.d.ts
CHANGED
|
@@ -1,4 +1,12 @@
|
|
|
1
|
+
import type { components } from "./schema.js";
|
|
1
2
|
declare const inspect: unique symbol;
|
|
3
|
+
/** Why a review request created nothing; `reason` names the setting to change. */
|
|
4
|
+
export type RunNowRefusal = components["schemas"]["RunNowRefusalView"];
|
|
5
|
+
export interface ProblemFields {
|
|
6
|
+
title?: string;
|
|
7
|
+
refusal?: RunNowRefusal;
|
|
8
|
+
repositoryName?: string;
|
|
9
|
+
}
|
|
2
10
|
export declare class SecretToken {
|
|
3
11
|
#private;
|
|
4
12
|
constructor(value: string);
|
|
@@ -10,9 +18,15 @@ export declare class SecretToken {
|
|
|
10
18
|
export declare class ProoflineError extends Error {
|
|
11
19
|
#private;
|
|
12
20
|
readonly status: number;
|
|
13
|
-
constructor(status: number, type: string, detail: string);
|
|
21
|
+
constructor(status: number, type: string, detail: string, fields?: ProblemFields);
|
|
14
22
|
get type(): string;
|
|
15
23
|
get detail(): string;
|
|
24
|
+
/** The server's problem class, such as `invalid request`. */
|
|
25
|
+
get title(): string | undefined;
|
|
26
|
+
/** The typed refusal of a review request that created nothing. */
|
|
27
|
+
get refusal(): RunNowRefusal | undefined;
|
|
28
|
+
/** The refused repository's name within its owner. */
|
|
29
|
+
get repositoryName(): string | undefined;
|
|
16
30
|
toJSON(): {
|
|
17
31
|
status: number;
|
|
18
32
|
};
|
package/dist/transport.js
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
|
-
const VERSION = "
|
|
1
|
+
const VERSION = "5.0.1";
|
|
2
2
|
const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
|
|
3
3
|
const MAX_RETRIES = 3;
|
|
4
4
|
const MAX_RETRY_SECONDS = 60;
|
|
5
5
|
const inspect = Symbol.for("nodejs.util.inspect.custom");
|
|
6
|
+
const secrets = new WeakMap();
|
|
6
7
|
export class SecretToken {
|
|
7
8
|
#value;
|
|
8
9
|
constructor(value) {
|
|
@@ -12,6 +13,7 @@ export class SecretToken {
|
|
|
12
13
|
throw new TypeError("a nonempty Proofline token without whitespace is required");
|
|
13
14
|
}
|
|
14
15
|
this.#value = value;
|
|
16
|
+
secrets.set(this, value);
|
|
15
17
|
}
|
|
16
18
|
apply(headers) {
|
|
17
19
|
headers.set("Authorization", `Bearer ${this.#value}`);
|
|
@@ -30,12 +32,14 @@ export class ProoflineError extends Error {
|
|
|
30
32
|
status;
|
|
31
33
|
#problemType;
|
|
32
34
|
#detail;
|
|
33
|
-
|
|
35
|
+
#fields;
|
|
36
|
+
constructor(status, type, detail, fields = {}) {
|
|
34
37
|
super(`Proofline request failed with status ${status}`);
|
|
35
38
|
this.status = status;
|
|
36
39
|
this.name = "ProoflineError";
|
|
37
40
|
this.#problemType = type;
|
|
38
41
|
this.#detail = detail;
|
|
42
|
+
this.#fields = fields;
|
|
39
43
|
}
|
|
40
44
|
get type() {
|
|
41
45
|
return this.#problemType;
|
|
@@ -43,6 +47,18 @@ export class ProoflineError extends Error {
|
|
|
43
47
|
get detail() {
|
|
44
48
|
return this.#detail;
|
|
45
49
|
}
|
|
50
|
+
/** The server's problem class, such as `invalid request`. */
|
|
51
|
+
get title() {
|
|
52
|
+
return this.#fields.title;
|
|
53
|
+
}
|
|
54
|
+
/** The typed refusal of a review request that created nothing. */
|
|
55
|
+
get refusal() {
|
|
56
|
+
return this.#fields.refusal;
|
|
57
|
+
}
|
|
58
|
+
/** The refused repository's name within its owner. */
|
|
59
|
+
get repositoryName() {
|
|
60
|
+
return this.#fields.repositoryName;
|
|
61
|
+
}
|
|
46
62
|
toJSON() {
|
|
47
63
|
return { status: this.status };
|
|
48
64
|
}
|
|
@@ -135,13 +151,78 @@ async function decoded(response, deadline, signal, waitTimeout, decode) {
|
|
|
135
151
|
reader.releaseLock();
|
|
136
152
|
}
|
|
137
153
|
}
|
|
138
|
-
function
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
154
|
+
function record(value) {
|
|
155
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
156
|
+
}
|
|
157
|
+
function redacted(value, secret) {
|
|
158
|
+
if (typeof value === "string")
|
|
159
|
+
return secret ? value.replaceAll(secret, "[redacted]") : value;
|
|
160
|
+
if (Array.isArray(value))
|
|
161
|
+
return value.map((item) => redacted(item, secret));
|
|
162
|
+
if (record(value))
|
|
163
|
+
return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redacted(item, secret)]));
|
|
164
|
+
return value;
|
|
165
|
+
}
|
|
166
|
+
function environment(value) {
|
|
167
|
+
return (record(value) &&
|
|
168
|
+
["id", "external_key", "display_name", "status"].every((key) => typeof value[key] === "string"));
|
|
169
|
+
}
|
|
170
|
+
const always = () => true;
|
|
171
|
+
const linked = (view) => environment(view.environment);
|
|
172
|
+
const explained = (view) => typeof view.detail === "string";
|
|
173
|
+
// Keyed by every documented reason, so a contract change fails the type check.
|
|
174
|
+
const refusalShapes = {
|
|
175
|
+
TRIGGER_DISABLED: always,
|
|
176
|
+
REPOSITORY_DISABLED: always,
|
|
177
|
+
NO_LINKED_ENVIRONMENT: always,
|
|
178
|
+
ENVIRONMENT_REVIEWS_OFF: linked,
|
|
179
|
+
ENVIRONMENT_NOT_READY: (view) => linked(view) &&
|
|
180
|
+
(view.status_detail === undefined ||
|
|
181
|
+
view.status_detail === null ||
|
|
182
|
+
typeof view.status_detail === "string"),
|
|
183
|
+
ENVIRONMENT_EVIDENCE_UNAVAILABLE: linked,
|
|
184
|
+
INVALID_DELIVERY_CONFIGURATION: (view) => explained(view) &&
|
|
185
|
+
(view.environment === undefined ||
|
|
186
|
+
view.environment === null ||
|
|
187
|
+
environment(view.environment)),
|
|
188
|
+
PULL_REQUEST_UNKNOWN: always,
|
|
189
|
+
AUTHOR_HAS_NO_SEAT: always,
|
|
190
|
+
PULL_REQUEST_CLOSED: always,
|
|
191
|
+
};
|
|
192
|
+
function refusal(value) {
|
|
193
|
+
if (!record(value) || typeof value.reason !== "string")
|
|
194
|
+
return undefined;
|
|
195
|
+
const shape = Object.hasOwn(refusalShapes, value.reason)
|
|
196
|
+
? refusalShapes[value.reason]
|
|
197
|
+
: undefined;
|
|
198
|
+
return shape?.(value) ? value : undefined;
|
|
199
|
+
}
|
|
200
|
+
function problem(status, value, token) {
|
|
201
|
+
if (!record(value))
|
|
202
|
+
return new ProoflineError(status, "about:blank", "the server refused the request without a problem detail");
|
|
203
|
+
const body = redacted(value, secrets.get(token) ?? "");
|
|
204
|
+
const type = typeof body.type === "string" ? body.type : "about:blank";
|
|
205
|
+
const title = typeof body.title === "string" ? body.title : undefined;
|
|
206
|
+
const detail = typeof body.detail === "string"
|
|
143
207
|
? body.detail
|
|
144
|
-
:
|
|
208
|
+
: title === undefined
|
|
209
|
+
? "the server refused the request without a problem detail"
|
|
210
|
+
: // Logged internal errors omit detail; the problem itself still arrived.
|
|
211
|
+
`the server returned the problem "${title}" without a detail`;
|
|
212
|
+
const fields = title === undefined ? {} : { title };
|
|
213
|
+
if (!("refusal" in body))
|
|
214
|
+
return new ProoflineError(status, type, detail, fields);
|
|
215
|
+
const view = refusal(body.refusal);
|
|
216
|
+
if (view === undefined ||
|
|
217
|
+
typeof body.repository_name !== "string" ||
|
|
218
|
+
typeof body.detail !== "string" ||
|
|
219
|
+
title === undefined)
|
|
220
|
+
return new ProoflineError(status, "urn:proofline:sdk:invalid-response", detail, fields);
|
|
221
|
+
return new ProoflineError(status, type, detail, {
|
|
222
|
+
title,
|
|
223
|
+
refusal: view,
|
|
224
|
+
repositoryName: body.repository_name,
|
|
225
|
+
});
|
|
145
226
|
}
|
|
146
227
|
function retryDelay(header, attempt) {
|
|
147
228
|
if (header === null)
|
|
@@ -261,7 +342,7 @@ export class Transport {
|
|
|
261
342
|
const value = await decoded(response, requestDeadline, signal, waitTimeout, decode);
|
|
262
343
|
if (response.ok)
|
|
263
344
|
return value;
|
|
264
|
-
const error = problem(response.status, value);
|
|
345
|
+
const error = problem(response.status, value, this.#token);
|
|
265
346
|
const delay = retryDelay(response.headers.get("Retry-After"), attempt);
|
|
266
347
|
if (method !== "GET" ||
|
|
267
348
|
![429, 503].includes(response.status) ||
|
package/openapi.public.json
CHANGED
|
@@ -807,7 +807,7 @@
|
|
|
807
807
|
"description": "The coverage reports a CI run produced for one commit.",
|
|
808
808
|
"properties": {
|
|
809
809
|
"reports": {
|
|
810
|
-
"description": "One to 50 reports, each LCOV, Cobertura XML, `JaCoCo` XML or a Go\n cover profile, in a JSON body of at most
|
|
810
|
+
"description": "One to 50 reports, each LCOV, Cobertura XML, `JaCoCo` XML or a Go\n cover profile, in a JSON body of at most 30 MiB.",
|
|
811
811
|
"items": {
|
|
812
812
|
"$ref": "#/components/schemas/UploadedReport"
|
|
813
813
|
},
|
|
@@ -5793,7 +5793,7 @@
|
|
|
5793
5793
|
},
|
|
5794
5794
|
"info": {
|
|
5795
5795
|
"title": "Proofline Review API",
|
|
5796
|
-
"version": "
|
|
5796
|
+
"version": "5.0.0"
|
|
5797
5797
|
},
|
|
5798
5798
|
"openapi": "3.1.0",
|
|
5799
5799
|
"paths": {
|
|
@@ -6305,7 +6305,7 @@
|
|
|
6305
6305
|
},
|
|
6306
6306
|
"400": {
|
|
6307
6307
|
"content": {
|
|
6308
|
-
"application/json": {
|
|
6308
|
+
"application/problem+json": {
|
|
6309
6309
|
"schema": {
|
|
6310
6310
|
"$ref": "#/components/schemas/RunNowRefused"
|
|
6311
6311
|
}
|
|
@@ -6393,7 +6393,7 @@
|
|
|
6393
6393
|
},
|
|
6394
6394
|
"422": {
|
|
6395
6395
|
"content": {
|
|
6396
|
-
"application/json": {
|
|
6396
|
+
"application/problem+json": {
|
|
6397
6397
|
"schema": {
|
|
6398
6398
|
"$ref": "#/components/schemas/CoverageRefused"
|
|
6399
6399
|
}
|
|
@@ -6471,7 +6471,7 @@
|
|
|
6471
6471
|
},
|
|
6472
6472
|
"400": {
|
|
6473
6473
|
"content": {
|
|
6474
|
-
"application/json": {
|
|
6474
|
+
"application/problem+json": {
|
|
6475
6475
|
"schema": {
|
|
6476
6476
|
"$ref": "#/components/schemas/RunNowRefused"
|
|
6477
6477
|
}
|
|
@@ -6549,7 +6549,7 @@
|
|
|
6549
6549
|
},
|
|
6550
6550
|
"400": {
|
|
6551
6551
|
"content": {
|
|
6552
|
-
"application/json": {
|
|
6552
|
+
"application/problem+json": {
|
|
6553
6553
|
"schema": {
|
|
6554
6554
|
"$ref": "#/components/schemas/RunNowRefused"
|
|
6555
6555
|
}
|
|
@@ -6636,7 +6636,7 @@
|
|
|
6636
6636
|
},
|
|
6637
6637
|
"400": {
|
|
6638
6638
|
"content": {
|
|
6639
|
-
"application/json": {
|
|
6639
|
+
"application/problem+json": {
|
|
6640
6640
|
"schema": {
|
|
6641
6641
|
"$ref": "#/components/schemas/RunNowRefused"
|
|
6642
6642
|
}
|
|
@@ -6771,7 +6771,7 @@
|
|
|
6771
6771
|
},
|
|
6772
6772
|
"400": {
|
|
6773
6773
|
"content": {
|
|
6774
|
-
"application/json": {
|
|
6774
|
+
"application/problem+json": {
|
|
6775
6775
|
"schema": {
|
|
6776
6776
|
"$ref": "#/components/schemas/RunNowRefused"
|
|
6777
6777
|
}
|