@proofline/sdk 3.3.1 → 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
@@ -3027,7 +3027,7 @@ export interface components {
3027
3027
  * @description Whether an explicit request may reuse a settled review of the live head.
3028
3028
  * @enum {string}
3029
3029
  */
3030
- RunNowMode: "EXISTING_OR_NEW" | "FULL" | "EXTENDED";
3030
+ RunNowMode: "EXISTING_OR_NEW" | "FULL";
3031
3031
  /**
3032
3032
  * @description Why a run-now request created nothing, each reason with what the page
3033
3033
  * needs to link the setting to change.
@@ -3068,13 +3068,6 @@ export interface components {
3068
3068
  } | {
3069
3069
  /** @constant */
3070
3070
  reason: "PULL_REQUEST_CLOSED";
3071
- } | {
3072
- detail: string;
3073
- /** @constant */
3074
- reason: "DEEP_REVIEW_UNAVAILABLE";
3075
- } | {
3076
- /** @constant */
3077
- reason: "DEEP_REVIEW_FOCUS_CONFLICT";
3078
3071
  };
3079
3072
  /**
3080
3073
  * @description A run-now request that created nothing, as the 400 it is answered with.
@@ -3106,15 +3099,9 @@ export interface components {
3106
3099
  };
3107
3100
  /** @description An empty body keeps the run-now behavior existing clients request. */
3108
3101
  RunNowRequest: {
3109
- /**
3110
- * @description Optional investigation focus for EXTENDED, trimmed and frozen at admission.
3111
- * Limited to 500 UTF-16 code units.
3112
- */
3113
- focus_text?: string | null;
3114
3102
  /**
3115
3103
  * @description `EXISTING_OR_NEW`, the default, returns any review that already owns the live head.
3116
3104
  * `FULL` returns a pending or running review of that head or starts a new one.
3117
- * `EXTENDED` admits one funded Deep Review for that head, with optional focus.
3118
3105
  */
3119
3106
  mode?: components["schemas"]["RunNowMode"];
3120
3107
  };
@@ -3723,7 +3710,7 @@ export interface operations {
3723
3710
  [name: string]: unknown;
3724
3711
  };
3725
3712
  content: {
3726
- "application/json": components["schemas"]["RunNowRefused"];
3713
+ "application/problem+json": components["schemas"]["RunNowRefused"];
3727
3714
  };
3728
3715
  };
3729
3716
  /** @description An RFC 9457 problem; the HTTP status remains authoritative. */
@@ -3781,7 +3768,7 @@ export interface operations {
3781
3768
  [name: string]: unknown;
3782
3769
  };
3783
3770
  content: {
3784
- "application/json": components["schemas"]["CoverageRefused"];
3771
+ "application/problem+json": components["schemas"]["CoverageRefused"];
3785
3772
  };
3786
3773
  };
3787
3774
  /** @description An RFC 9457 problem; the HTTP status remains authoritative. */
@@ -3836,7 +3823,7 @@ export interface operations {
3836
3823
  [name: string]: unknown;
3837
3824
  };
3838
3825
  content: {
3839
- "application/json": components["schemas"]["RunNowRefused"];
3826
+ "application/problem+json": components["schemas"]["RunNowRefused"];
3840
3827
  };
3841
3828
  };
3842
3829
  /** @description An RFC 9457 problem; the HTTP status remains authoritative. */
@@ -3891,7 +3878,7 @@ export interface operations {
3891
3878
  [name: string]: unknown;
3892
3879
  };
3893
3880
  content: {
3894
- "application/json": components["schemas"]["RunNowRefused"];
3881
+ "application/problem+json": components["schemas"]["RunNowRefused"];
3895
3882
  };
3896
3883
  };
3897
3884
  /** @description An RFC 9457 problem; the HTTP status remains authoritative. */
@@ -3950,7 +3937,7 @@ export interface operations {
3950
3937
  [name: string]: unknown;
3951
3938
  };
3952
3939
  content: {
3953
- "application/json": components["schemas"]["RunNowRefused"];
3940
+ "application/problem+json": components["schemas"]["RunNowRefused"];
3954
3941
  };
3955
3942
  };
3956
3943
  /** @description An RFC 9457 problem; the HTTP status remains authoritative. */
@@ -4036,7 +4023,7 @@ export interface operations {
4036
4023
  [name: string]: unknown;
4037
4024
  };
4038
4025
  content: {
4039
- "application/json": components["schemas"]["RunNowRefused"];
4026
+ "application/problem+json": components["schemas"]["RunNowRefused"];
4040
4027
  };
4041
4028
  };
4042
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 = "3.3.1";
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) ||
@@ -4942,8 +4942,7 @@
4942
4942
  "description": "Whether an explicit request may reuse a settled review of the live head.",
4943
4943
  "enum": [
4944
4944
  "EXISTING_OR_NEW",
4945
- "FULL",
4946
- "EXTENDED"
4945
+ "FULL"
4947
4946
  ],
4948
4947
  "type": "string"
4949
4948
  },
@@ -5111,36 +5110,6 @@
5111
5110
  "reason"
5112
5111
  ],
5113
5112
  "type": "object"
5114
- },
5115
- {
5116
- "description": "Deep review policy, funding or worker availability prevents admission.",
5117
- "properties": {
5118
- "detail": {
5119
- "type": "string"
5120
- },
5121
- "reason": {
5122
- "const": "DEEP_REVIEW_UNAVAILABLE",
5123
- "type": "string"
5124
- }
5125
- },
5126
- "required": [
5127
- "reason",
5128
- "detail"
5129
- ],
5130
- "type": "object"
5131
- },
5132
- {
5133
- "description": "The existing review already retains a different focus.",
5134
- "properties": {
5135
- "reason": {
5136
- "const": "DEEP_REVIEW_FOCUS_CONFLICT",
5137
- "type": "string"
5138
- }
5139
- },
5140
- "required": [
5141
- "reason"
5142
- ],
5143
- "type": "object"
5144
5113
  }
5145
5114
  ]
5146
5115
  },
@@ -5188,20 +5157,13 @@
5188
5157
  "additionalProperties": false,
5189
5158
  "description": "An empty body keeps the run-now behavior existing clients request.",
5190
5159
  "properties": {
5191
- "focus_text": {
5192
- "description": "Optional investigation focus for EXTENDED, trimmed and frozen at admission.\n Limited to 500 UTF-16 code units.",
5193
- "type": [
5194
- "string",
5195
- "null"
5196
- ]
5197
- },
5198
5160
  "mode": {
5199
5161
  "allOf": [
5200
5162
  {
5201
5163
  "$ref": "#/components/schemas/RunNowMode"
5202
5164
  }
5203
5165
  ],
5204
- "description": "`EXISTING_OR_NEW`, the default, returns any review that already owns the live head.\n `FULL` returns a pending or running review of that head or starts a new one.\n `EXTENDED` admits one funded Deep Review for that head, with optional focus."
5166
+ "description": "`EXISTING_OR_NEW`, the default, returns any review that already owns the live head.\n `FULL` returns a pending or running review of that head or starts a new one."
5205
5167
  }
5206
5168
  },
5207
5169
  "type": "object"
@@ -5831,7 +5793,7 @@
5831
5793
  },
5832
5794
  "info": {
5833
5795
  "title": "Proofline Review API",
5834
- "version": "3.3.0"
5796
+ "version": "5.0.0"
5835
5797
  },
5836
5798
  "openapi": "3.1.0",
5837
5799
  "paths": {
@@ -6343,7 +6305,7 @@
6343
6305
  },
6344
6306
  "400": {
6345
6307
  "content": {
6346
- "application/json": {
6308
+ "application/problem+json": {
6347
6309
  "schema": {
6348
6310
  "$ref": "#/components/schemas/RunNowRefused"
6349
6311
  }
@@ -6431,7 +6393,7 @@
6431
6393
  },
6432
6394
  "422": {
6433
6395
  "content": {
6434
- "application/json": {
6396
+ "application/problem+json": {
6435
6397
  "schema": {
6436
6398
  "$ref": "#/components/schemas/CoverageRefused"
6437
6399
  }
@@ -6509,7 +6471,7 @@
6509
6471
  },
6510
6472
  "400": {
6511
6473
  "content": {
6512
- "application/json": {
6474
+ "application/problem+json": {
6513
6475
  "schema": {
6514
6476
  "$ref": "#/components/schemas/RunNowRefused"
6515
6477
  }
@@ -6587,7 +6549,7 @@
6587
6549
  },
6588
6550
  "400": {
6589
6551
  "content": {
6590
- "application/json": {
6552
+ "application/problem+json": {
6591
6553
  "schema": {
6592
6554
  "$ref": "#/components/schemas/RunNowRefused"
6593
6555
  }
@@ -6674,7 +6636,7 @@
6674
6636
  },
6675
6637
  "400": {
6676
6638
  "content": {
6677
- "application/json": {
6639
+ "application/problem+json": {
6678
6640
  "schema": {
6679
6641
  "$ref": "#/components/schemas/RunNowRefused"
6680
6642
  }
@@ -6809,7 +6771,7 @@
6809
6771
  },
6810
6772
  "400": {
6811
6773
  "content": {
6812
- "application/json": {
6774
+ "application/problem+json": {
6813
6775
  "schema": {
6814
6776
  "$ref": "#/components/schemas/RunNowRefused"
6815
6777
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@proofline/sdk",
3
- "version": "3.3.1",
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",