@proofline/sdk 4.0.0 → 5.0.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 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.
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
@@ -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. */
@@ -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 = "4.0.0";
1
+ const VERSION = "5.0.0";
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
- constructor(status, type, detail) {
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 problem(status, value) {
139
- const body = value !== null && typeof value === "object"
140
- ? value
141
- : {};
142
- return new ProoflineError(status, typeof body.type === "string" ? body.type : "about:blank", typeof body.detail === "string"
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
- : "the server refused the request without a problem detail");
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) ||
@@ -5793,7 +5793,7 @@
5793
5793
  },
5794
5794
  "info": {
5795
5795
  "title": "Proofline Review API",
5796
- "version": "4.0.0"
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
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@proofline/sdk",
3
- "version": "4.0.0",
3
+ "version": "5.0.0",
4
4
  "description": "Typed clients for the token-scoped Proofline review API",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",