@proofline/sdk 3.1.0 → 3.3.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
@@ -55,6 +55,27 @@ process.stdout.write(page.text);
55
55
  // Continue with query.cursor = page.nextCursor when it is not null.
56
56
  ```
57
57
 
58
+ ## MCP organization selection
59
+
60
+ With an MCP OAuth credential approved for several organizations, call `client.mcp.listOrganizations()` to discover its currently authorized targets. The `KnowledgeResult` retains `isError` and `structuredContent.data.organizations`; each organization entry contains `organization_id`, `github_login`, and `scopes`.
61
+
62
+ Every `knowledge` and `fixes` helper accepts an optional organization UUID string. Object-taking methods accept `organization_id` in their argument object. Methods taking scalar arguments accept a final `McpTarget` options object:
63
+
64
+ ```typescript
65
+ const organizations = await client.mcp.listOrganizations();
66
+ if (organizations.isError) throw new Error("Organization discovery was refused.");
67
+ console.log(organizations.structuredContent?.data);
68
+ // Set organizationId to the UUID of the organization you intend to use.
69
+ const context = await client.fixes.getFixContext(findingId, {
70
+ organization_id: organizationId,
71
+ });
72
+ const page = await client.knowledge.getWikiPage({
73
+ repository: "owner/name", page_key: "index", organization_id: organizationId,
74
+ });
75
+ ```
76
+
77
+ Selection applies only to that call, including concurrent calls on one client. A single-organization credential can omit it. An ambiguous omission retains the server's `ORGANIZATION_REQUIRED` tool refusal; a foreign or revoked target retains `NOT_AUTHORIZED` and `isError`. The SDK chooses no default and never retries a tool call. Discovery and targeting use MCP only; an MCP OAuth credential cannot call the REST API. Each organization's scopes and repository restrictions still apply.
78
+
58
79
  ## Knowledge and plans
59
80
 
60
81
  `client.knowledge` provides typed MCP methods: `listWikiPages`, `getWikiPage`, `askCodebase`, `getArchitectureDocument`, `getPlan`, `startPlanImplementation`, and `getPlanImplementation`.
package/dist/fixes.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { type KnowledgeResult, McpTools } from "./mcp.js";
2
- export interface ReverificationRequest {
1
+ import { type KnowledgeResult, type McpTarget, McpTools } from "./mcp.js";
2
+ export interface ReverificationRequest extends McpTarget {
3
3
  review_id: string;
4
4
  finding_ids: string[];
5
5
  commit_sha: string;
@@ -7,8 +7,8 @@ export interface ReverificationRequest {
7
7
  }
8
8
  /** Fix context and pushed-head verification. Tool refusals retain isError. */
9
9
  export declare class FixesClient extends McpTools {
10
- listOpenFindings(repository: string, pullRequestNumber: number): Promise<KnowledgeResult>;
11
- getFixContext(findingId: string): Promise<KnowledgeResult>;
10
+ listOpenFindings(repository: string, pullRequestNumber: number, options?: McpTarget): Promise<KnowledgeResult>;
11
+ getFixContext(findingId: string, options?: McpTarget): Promise<KnowledgeResult>;
12
12
  requestReverification(args: ReverificationRequest): Promise<KnowledgeResult>;
13
- getReverification(requestId: string): Promise<KnowledgeResult>;
13
+ getReverification(requestId: string, options?: McpTarget): Promise<KnowledgeResult>;
14
14
  }
package/dist/fixes.js CHANGED
@@ -1,19 +1,26 @@
1
1
  import { McpTools } from "./mcp.js";
2
2
  /** Fix context and pushed-head verification. Tool refusals retain isError. */
3
3
  export class FixesClient extends McpTools {
4
- listOpenFindings(repository, pullRequestNumber) {
4
+ listOpenFindings(repository, pullRequestNumber, options = {}) {
5
5
  return this.call("list_open_findings", {
6
6
  repository,
7
7
  pull_request_number: pullRequestNumber,
8
+ organization_id: options.organization_id,
8
9
  });
9
10
  }
10
- getFixContext(findingId) {
11
- return this.call("get_fix_context", { finding_id: findingId });
11
+ getFixContext(findingId, options = {}) {
12
+ return this.call("get_fix_context", {
13
+ finding_id: findingId,
14
+ organization_id: options.organization_id,
15
+ });
12
16
  }
13
17
  requestReverification(args) {
14
18
  return this.call("request_reverification", args);
15
19
  }
16
- getReverification(requestId) {
17
- return this.call("get_reverification", { request_id: requestId });
20
+ getReverification(requestId, options = {}) {
21
+ return this.call("get_reverification", {
22
+ request_id: requestId,
23
+ organization_id: options.organization_id,
24
+ });
18
25
  }
19
26
  }
package/dist/index.d.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  import { FixesClient } from "./fixes.js";
2
2
  export type { ReverificationRequest } from "./fixes.js";
3
+ import { McpClient } from "./mcp.js";
4
+ export type { McpTarget } from "./mcp.js";
3
5
  import { KnowledgeClient } from "./knowledge.js";
4
6
  export type { KnowledgeResult, RepositoryKnowledge } from "./knowledge.js";
5
7
  import { type ExportPage, type ExportParameters } from "./exports.js";
@@ -15,6 +17,7 @@ export type Review = components["schemas"]["CustomerReviewDetail"];
15
17
  export type Assessment = components["schemas"]["CustomerAssessment"];
16
18
  export type ReviewStatus = "COMPLETED" | "INCOMPLETE" | "FAILED" | "STOPPED" | "TIMED_OUT";
17
19
  export interface AssessmentGaps {
20
+ /** Empty when no assessment identity is available for this gap. */
18
21
  assessmentId: string;
19
22
  status: string;
20
23
  incompletenessKind: string | null;
@@ -39,6 +42,7 @@ export interface WaitOptions {
39
42
  }
40
43
  export declare class ProoflineClient extends Operations {
41
44
  #private;
45
+ readonly mcp: McpClient;
42
46
  readonly knowledge: KnowledgeClient;
43
47
  readonly fixes: FixesClient;
44
48
  constructor(options: ClientOptions);
package/dist/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { FixesClient } from "./fixes.js";
2
+ import { McpClient } from "./mcp.js";
2
3
  import { KnowledgeClient } from "./knowledge.js";
3
4
  import { decodeExport, } from "./exports.js";
4
5
  import { Operations } from "./operations.js";
@@ -6,12 +7,14 @@ import { sleep, Transport } from "./transport.js";
6
7
  export { ProoflineError, SecretToken } from "./transport.js";
7
8
  export class ProoflineClient extends Operations {
8
9
  #transport;
10
+ mcp;
9
11
  knowledge;
10
12
  fixes;
11
13
  constructor(options) {
12
14
  const transport = new Transport(options);
13
15
  super((method, path, parameters, body) => transport.request(method, path, parameters, undefined, body));
14
16
  this.#transport = transport;
17
+ this.mcp = new McpClient(transport);
15
18
  this.knowledge = new KnowledgeClient(transport);
16
19
  this.fixes = new FixesClient(transport);
17
20
  }
@@ -123,7 +126,9 @@ const KNOWN_ASSESSMENTS = new Set([
123
126
  "FAILED",
124
127
  "SUPERSEDED",
125
128
  "STOPPED",
129
+ "EXCLUDED",
126
130
  ]);
131
+ const WITHHELD_MARKER = "[withheld: environment value]";
127
132
  function isObject(value) {
128
133
  return value !== null && typeof value === "object" && !Array.isArray(value);
129
134
  }
@@ -185,6 +190,8 @@ function checkGap(assessment) {
185
190
  function terminal(review) {
186
191
  if (review.status === "PENDING" || review.status === "RUNNING")
187
192
  return null;
193
+ if (review.status === "SUPERSEDED")
194
+ return "STOPPED";
188
195
  if (review.status === "FAILED" ||
189
196
  review.status === "STOPPED" ||
190
197
  review.status === "INCOMPLETE")
@@ -224,8 +231,32 @@ function codeAssessment(review) {
224
231
  code.incompleteness_kind !== undefined &&
225
232
  typeof code.incompleteness_kind !== "string"))
226
233
  return null;
234
+ if ((typeof review.head_commit_sha === "string" &&
235
+ review.head_commit_sha.toLowerCase() !==
236
+ code.head_commit_sha.toLowerCase()) ||
237
+ (typeof review.base_commit_sha === "string" &&
238
+ review.base_commit_sha.toLowerCase() !==
239
+ code.base_commit_sha.toLowerCase()) ||
240
+ code.findings.some((finding) => finding.risk_domain === WITHHELD_MARKER))
241
+ return null;
227
242
  return code;
228
243
  }
244
+ function assessmentReasons(assessment) {
245
+ const reasons = [...(assessment.reason_codes ?? [])];
246
+ if (assessment.incompleteness_kind)
247
+ reasons.push(assessment.incompleteness_kind);
248
+ if (assessment.release_evidence_gap)
249
+ reasons.push(assessment.release_evidence_gap);
250
+ if (checkGap(assessment))
251
+ reasons.push(assessment.checks.receipt_recorded
252
+ ? "CHECKS_UNRESOLVED"
253
+ : "CHECK_RECEIPT_ABSENT");
254
+ if (!reasons.length)
255
+ reasons.push(KNOWN_ASSESSMENTS.has(assessment.status)
256
+ ? "ASSESSMENT_RESULT_UNAVAILABLE"
257
+ : "UNKNOWN_ASSESSMENT_STATUS");
258
+ return reasons;
259
+ }
229
260
  function outcome(status, reviewUrl, review, reason) {
230
261
  const gaps = (review?.assessments ?? [])
231
262
  .filter((assessment) => assessment.status !== "COMPLETED" ||
@@ -237,13 +268,7 @@ function outcome(status, reviewUrl, review, reason) {
237
268
  assessmentId: assessment.id,
238
269
  status: assessment.status,
239
270
  incompletenessKind: assessment.incompleteness_kind ?? null,
240
- reasonCodes: assessment.reason_codes?.length
241
- ? assessment.reason_codes
242
- : [
243
- !KNOWN_ASSESSMENTS.has(assessment.status)
244
- ? "UNKNOWN_ASSESSMENT_STATUS"
245
- : "ASSESSMENT_RESULT_UNAVAILABLE",
246
- ],
271
+ reasonCodes: assessmentReasons(assessment),
247
272
  releaseEvidenceGap: assessment.release_evidence_gap ?? null,
248
273
  checks: assessment.checks.families
249
274
  .filter((check) => !COMPLETE_CHECKS.has(check.outcome) ||
@@ -262,11 +287,53 @@ function outcome(status, reviewUrl, review, reason) {
262
287
  status: code.status,
263
288
  incompletenessKind: code.incompleteness_kind ?? null,
264
289
  reasonCodes: code.incompleteness_kind
265
- ? []
290
+ ? [code.incompleteness_kind]
266
291
  : ["CODE_ASSESSMENT_STATE_UNAVAILABLE"],
267
292
  releaseEvidenceGap: null,
268
293
  checks: [],
269
294
  });
270
295
  }
296
+ if (review &&
297
+ review.assessment_count === 0 &&
298
+ !review.assessments.length &&
299
+ !code) {
300
+ gaps.push({
301
+ assessmentId: "",
302
+ status: "UNKNOWN",
303
+ incompletenessKind: null,
304
+ reasonCodes: ["CODE_ASSESSMENT_UNAVAILABLE"],
305
+ releaseEvidenceGap: null,
306
+ checks: [],
307
+ });
308
+ }
309
+ if (review && review.assessment_count !== review.assessments.length) {
310
+ gaps.push({
311
+ assessmentId: "",
312
+ status: "UNKNOWN",
313
+ incompletenessKind: null,
314
+ reasonCodes: ["ASSESSMENT_HISTORY_UNAVAILABLE"],
315
+ releaseEvidenceGap: null,
316
+ checks: [],
317
+ });
318
+ }
319
+ if (review &&
320
+ !gaps.length &&
321
+ ![
322
+ "PENDING",
323
+ "RUNNING",
324
+ "COMPLETED",
325
+ "FAILED",
326
+ "STOPPED",
327
+ "SUPERSEDED",
328
+ ].includes(review.status)) {
329
+ gaps.push({
330
+ assessmentId: "",
331
+ status: review.status,
332
+ incompletenessKind: null,
333
+ reasonCodes: ["REVIEW_STATE_UNAVAILABLE"],
334
+ releaseEvidenceGap: null,
335
+ checks: [],
336
+ });
337
+ }
271
338
  return { status, reviewUrl, review, gaps, reason };
272
339
  }
@@ -1,4 +1,4 @@
1
- import { type KnowledgeResult, McpTools } from "./mcp.js";
1
+ import { type KnowledgeResult, type McpTarget, McpTools } from "./mcp.js";
2
2
  export type { KnowledgeResult, RepositoryKnowledge } from "./mcp.js";
3
3
  import type { RepositoryKnowledge } from "./mcp.js";
4
4
  /** Published knowledge operations through the scoped MCP server. */
@@ -10,8 +10,8 @@ export declare class KnowledgeClient extends McpTools {
10
10
  askCodebase(args: RepositoryKnowledge & {
11
11
  question: string;
12
12
  }): Promise<KnowledgeResult>;
13
- getArchitectureDocument(environmentId: string): Promise<KnowledgeResult>;
14
- getPlan(planId: string): Promise<KnowledgeResult>;
15
- startPlanImplementation(planId: string): Promise<KnowledgeResult>;
16
- getPlanImplementation(implementationId: string): Promise<KnowledgeResult>;
13
+ getArchitectureDocument(environmentId: string, options?: McpTarget): Promise<KnowledgeResult>;
14
+ getPlan(planId: string, options?: McpTarget): Promise<KnowledgeResult>;
15
+ startPlanImplementation(planId: string, options?: McpTarget): Promise<KnowledgeResult>;
16
+ getPlanImplementation(implementationId: string, options?: McpTarget): Promise<KnowledgeResult>;
17
17
  }
package/dist/knowledge.js CHANGED
@@ -10,20 +10,28 @@ export class KnowledgeClient extends McpTools {
10
10
  askCodebase(args) {
11
11
  return this.call("ask_codebase", args);
12
12
  }
13
- getArchitectureDocument(environmentId) {
13
+ getArchitectureDocument(environmentId, options = {}) {
14
14
  return this.call("get_architecture_document", {
15
15
  environment_id: environmentId,
16
+ organization_id: options.organization_id,
16
17
  });
17
18
  }
18
- getPlan(planId) {
19
- return this.call("get_plan", { plan_id: planId });
19
+ getPlan(planId, options = {}) {
20
+ return this.call("get_plan", {
21
+ plan_id: planId,
22
+ organization_id: options.organization_id,
23
+ });
20
24
  }
21
- startPlanImplementation(planId) {
22
- return this.call("start_plan_implementation", { plan_id: planId });
25
+ startPlanImplementation(planId, options = {}) {
26
+ return this.call("start_plan_implementation", {
27
+ plan_id: planId,
28
+ organization_id: options.organization_id,
29
+ });
23
30
  }
24
- getPlanImplementation(implementationId) {
31
+ getPlanImplementation(implementationId, options = {}) {
25
32
  return this.call("get_plan_implementation", {
26
33
  implementation_id: implementationId,
34
+ organization_id: options.organization_id,
27
35
  });
28
36
  }
29
37
  }
package/dist/mcp.d.ts CHANGED
@@ -8,7 +8,11 @@ export interface KnowledgeResult {
8
8
  structuredContent?: Record<string, unknown>;
9
9
  isError?: boolean;
10
10
  }
11
- export interface RepositoryKnowledge {
11
+ /** Selects one authorized organization for this call only. */
12
+ export interface McpTarget {
13
+ organization_id?: string;
14
+ }
15
+ export interface RepositoryKnowledge extends McpTarget {
12
16
  repository: string;
13
17
  commit?: string;
14
18
  }
@@ -18,3 +22,7 @@ export declare class McpTools {
18
22
  constructor(transport: Transport);
19
23
  protected call(name: string, args: object): Promise<KnowledgeResult>;
20
24
  }
25
+ /** Discover the organizations currently authorized for this MCP credential. */
26
+ export declare class McpClient extends McpTools {
27
+ listOrganizations(): Promise<KnowledgeResult>;
28
+ }
package/dist/mcp.js CHANGED
@@ -22,6 +22,8 @@ export class McpTools {
22
22
  this.transport = transport;
23
23
  }
24
24
  async call(name, args) {
25
+ // Bind the per-call target before protocol negotiation yields to the caller.
26
+ const callArguments = { ...args };
25
27
  const invoke = (body, phase) => this.transport.request("POST", "/mcp", {}, undefined, body, (text) => {
26
28
  if (phase === "notification") {
27
29
  if (text !== "")
@@ -47,7 +49,7 @@ export class McpTools {
47
49
  jsonrpc: "2.0",
48
50
  id: 2,
49
51
  method: "tools/call",
50
- params: { name, arguments: args },
52
+ params: { name, arguments: callArguments },
51
53
  }, "call"), 2);
52
54
  if (!Array.isArray(result.content) ||
53
55
  result.content.some((item) => !object(item) ||
@@ -60,3 +62,9 @@ export class McpTools {
60
62
  return result;
61
63
  }
62
64
  }
65
+ /** Discover the organizations currently authorized for this MCP credential. */
66
+ export class McpClient extends McpTools {
67
+ listOrganizations() {
68
+ return this.call("list_organizations", {});
69
+ }
70
+ }
@@ -17,6 +17,8 @@ export type RequestPatchReviewBody = NonNullable<paths["/api/v1/organizations/{o
17
17
  export type RequestReviewParameters = paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/pull-requests/{number}/review"]["post"]["parameters"];
18
18
  export type RequestReviewBody = NonNullable<paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/pull-requests/{number}/review"]["post"]["requestBody"]>["content"]["application/json"];
19
19
  export type GetReviewGuidanceParameters = paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/review-guidance"]["get"]["parameters"];
20
+ export type RequestScanParameters = paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/scans"]["post"]["parameters"];
21
+ export type RequestScanBody = NonNullable<paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/scans"]["post"]["requestBody"]>["content"]["application/json"];
20
22
  export type ListRepositoriesParameters = paths["/api/v1/organizations/{org_id}/repository-names"]["get"]["parameters"];
21
23
  export type ListReviewsParameters = paths["/api/v1/organizations/{org_id}/reviews"]["get"]["parameters"];
22
24
  export type GetDeploymentReviewParameters = paths["/api/v1/organizations/{org_id}/reviews/deployments/{public_key}"]["get"]["parameters"];
@@ -41,6 +43,7 @@ export declare class Operations {
41
43
  requestPatchReview(parameters: RequestPatchReviewParameters, body: RequestPatchReviewBody): Promise<components["schemas"]["PatchReviewResponse"]>;
42
44
  requestReview(parameters: RequestReviewParameters, body?: RequestReviewBody): Promise<components["schemas"]["RunNowResponse"]>;
43
45
  getReviewGuidance(parameters: GetReviewGuidanceParameters): Promise<components["schemas"]["RepositoryGuidance"]>;
46
+ requestScan(parameters: RequestScanParameters, body: RequestScanBody): Promise<components["schemas"]["ScanResponse"]>;
44
47
  listRepositories(parameters: ListRepositoriesParameters): Promise<components["schemas"]["RepositoryNames"]>;
45
48
  listReviews(parameters: ListReviewsParameters): Promise<components["schemas"]["ReviewPage"]>;
46
49
  getDeploymentReview(parameters: GetDeploymentReviewParameters): Promise<components["schemas"]["CustomerReviewDetail"]>;
@@ -36,6 +36,9 @@ export class Operations {
36
36
  getReviewGuidance(parameters) {
37
37
  return this.invoke("GET", "/api/v1/organizations/{org_id}/repositories/{repo_id}/review-guidance", parameters);
38
38
  }
39
+ requestScan(parameters, body) {
40
+ return this.invoke("POST", "/api/v1/organizations/{org_id}/repositories/{repo_id}/scans", parameters, body);
41
+ }
39
42
  listRepositories(parameters) {
40
43
  return this.invoke("GET", "/api/v1/organizations/{org_id}/repository-names", parameters);
41
44
  }
package/dist/schema.d.ts CHANGED
@@ -244,6 +244,26 @@ export interface paths {
244
244
  patch?: never;
245
245
  trace?: never;
246
246
  };
247
+ "/api/v1/organizations/{org_id}/repositories/{repo_id}/scans": {
248
+ parameters: {
249
+ query?: never;
250
+ header?: never;
251
+ path?: never;
252
+ cookie?: never;
253
+ };
254
+ get?: never;
255
+ put?: never;
256
+ /**
257
+ * Scan a repository revision
258
+ * @description Scans the whole repository at one commit, resolved once from `ref` or named by `commit_sha`, and records that resolution. Requires live GitHub write access, and `budget_credits` at most the organization's on-demand scan limit; a limit of 0 turns on-demand scans off. Sending the same `request_id` again returns the first resolution. Results remain in Proofline and are never posted to GitHub.
259
+ */
260
+ post: operations["request_scan"];
261
+ delete?: never;
262
+ options?: never;
263
+ head?: never;
264
+ patch?: never;
265
+ trace?: never;
266
+ };
247
267
  "/api/v1/organizations/{org_id}/repository-names": {
248
268
  parameters: {
249
269
  query?: never;
@@ -1400,8 +1420,9 @@ export interface components {
1400
1420
  /**
1401
1421
  * @description `PULL_REQUEST`, `DEPLOYMENT`, `PATCH`, a review of local changes
1402
1422
  * sent as a patch, `COMMIT`, a review of pushed commits, `FILES`,
1403
- * complete selected files at one pushed commit, or `MERGE_GROUP`, the
1404
- * commit GitHub's merge queue built for a group of pull requests.
1423
+ * complete selected files at one pushed commit, `MERGE_GROUP`, the
1424
+ * commit GitHub's merge queue built for a group of pull requests, or
1425
+ * `REVISION_SCAN`, a scan of one captured commit.
1405
1426
  */
1406
1427
  kind: string;
1407
1428
  /**
@@ -2802,8 +2823,9 @@ export interface components {
2802
2823
  /**
2803
2824
  * @description `PULL_REQUEST`, `DEPLOYMENT`, `PATCH`, a review of local changes
2804
2825
  * sent as a patch, `COMMIT`, a review of pushed commits, `FILES`,
2805
- * complete selected files at one pushed commit, or `MERGE_GROUP`, the
2806
- * commit GitHub's merge queue built for a group of pull requests.
2826
+ * complete selected files at one pushed commit, `MERGE_GROUP`, the
2827
+ * commit GitHub's merge queue built for a group of pull requests, or
2828
+ * `REVISION_SCAN`, a scan of one captured commit.
2807
2829
  */
2808
2830
  kind: string;
2809
2831
  /**
@@ -3123,6 +3145,44 @@ export interface components {
3123
3145
  */
3124
3146
  run_number: number;
3125
3147
  };
3148
+ /** @description One request to scan a ref or an exact commit of the repository. */
3149
+ ScanRequestBody: {
3150
+ /**
3151
+ * Format: int64
3152
+ * @description The credits the whole scan may spend, at most the organization's
3153
+ * on-demand ceiling.
3154
+ */
3155
+ budget_credits: number;
3156
+ /** @description An exact commit. Name it or `ref`. */
3157
+ commit_sha?: string | null;
3158
+ /** @description A ref, resolved once when the request arrives. Name it or `commit_sha`. */
3159
+ ref?: string | null;
3160
+ /**
3161
+ * Format: uuid
3162
+ * @description The caller's identity for this request. Sending it again returns the
3163
+ * first resolution instead of scanning again.
3164
+ */
3165
+ request_id: string;
3166
+ };
3167
+ /** @description What a scan request resolved to. */
3168
+ ScanResponse: {
3169
+ /**
3170
+ * @description `CREATED`, `EXISTING` when this request id was already resolved, or
3171
+ * `REPOSITORY_UNAVAILABLE` when GitHub could not resolve it.
3172
+ */
3173
+ outcome: string;
3174
+ /**
3175
+ * Format: uuid
3176
+ * @description The request's one resolution receipt.
3177
+ */
3178
+ resolution_id: string;
3179
+ /**
3180
+ * Format: uuid
3181
+ * @description The scan review, readable through the review routes. Absent when
3182
+ * GitHub could not resolve the request.
3183
+ */
3184
+ review_id?: string | null;
3185
+ };
3126
3186
  /** @enum {string} */
3127
3187
  SpendAccountKind: "DEPLOYMENT" | "TENANT_CREDENTIAL" | "UNATTRIBUTED";
3128
3188
  /** @description UTC daily debit totals using only the account and transport recorded at charge time. */
@@ -3935,6 +3995,61 @@ export interface operations {
3935
3995
  };
3936
3996
  };
3937
3997
  };
3998
+ request_scan: {
3999
+ parameters: {
4000
+ query?: never;
4001
+ header?: never;
4002
+ path: {
4003
+ org_id: string;
4004
+ repo_id: string;
4005
+ };
4006
+ cookie?: never;
4007
+ };
4008
+ /** @description One request to scan a ref or an exact commit of the repository. */
4009
+ requestBody: {
4010
+ content: {
4011
+ "application/json": components["schemas"]["ScanRequestBody"];
4012
+ };
4013
+ };
4014
+ responses: {
4015
+ /** @description What a scan request resolved to. */
4016
+ 200: {
4017
+ headers: {
4018
+ [name: string]: unknown;
4019
+ };
4020
+ content: {
4021
+ "application/json": components["schemas"]["ScanResponse"];
4022
+ };
4023
+ };
4024
+ /**
4025
+ * @description A run-now request that created nothing, as the 400 it is answered with.
4026
+ *
4027
+ * The refusal is a configuration fact, not a failure, and it is still sent
4028
+ * as an RFC 9457 problem: `title`, `status` and `detail` are what a client
4029
+ * that knows only problems shows, and `repository_name` and `refusal` are
4030
+ * the extension members a client that knows refusals links from. During a
4031
+ * rollout a page loaded from the previous bundle keeps working against
4032
+ * this server, because a refusal was a 400 with a `detail` before too.
4033
+ */
4034
+ 400: {
4035
+ headers: {
4036
+ [name: string]: unknown;
4037
+ };
4038
+ content: {
4039
+ "application/json": components["schemas"]["RunNowRefused"];
4040
+ };
4041
+ };
4042
+ /** @description An RFC 9457 problem; the HTTP status remains authoritative. */
4043
+ default: {
4044
+ headers: {
4045
+ [name: string]: unknown;
4046
+ };
4047
+ content: {
4048
+ "application/problem+json": components["schemas"]["Problem"];
4049
+ };
4050
+ };
4051
+ };
4052
+ };
3938
4053
  list_repositories: {
3939
4054
  parameters: {
3940
4055
  query?: never;
package/dist/transport.js CHANGED
@@ -1,4 +1,4 @@
1
- const VERSION = "3.1.0";
1
+ const VERSION = "3.3.0";
2
2
  const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
3
3
  const MAX_RETRIES = 3;
4
4
  const MAX_RETRY_SECONDS = 60;
@@ -85,6 +85,8 @@ function positive(value, name) {
85
85
  async function decoded(response, deadline, signal, waitTimeout, decode) {
86
86
  const reader = response.body?.getReader();
87
87
  if (!reader) {
88
+ if (!response.ok)
89
+ return undefined;
88
90
  throw new ProoflineError(response.status, "urn:proofline:sdk:invalid-response", "the response has no JSON body");
89
91
  }
90
92
  const chunks = [];
@@ -108,9 +110,15 @@ async function decoded(response, deadline, signal, waitTimeout, decode) {
108
110
  offset += chunk.length;
109
111
  }
110
112
  const text = new TextDecoder("utf-8", { fatal: true }).decode(data);
111
- return response.ok
112
- ? decode(text, response.headers)
113
- : JSON.parse(text);
113
+ if (response.ok)
114
+ return decode(text, response.headers);
115
+ try {
116
+ return JSON.parse(text);
117
+ }
118
+ catch {
119
+ // A complete HTTP refusal need not carry a JSON Problem to be retryable.
120
+ return undefined;
121
+ }
114
122
  }
115
123
  catch (error) {
116
124
  if (error instanceof ProoflineError)
@@ -1755,7 +1755,7 @@
1755
1755
  "type": "boolean"
1756
1756
  },
1757
1757
  "kind": {
1758
- "description": "`PULL_REQUEST`, `DEPLOYMENT`, `PATCH`, a review of local changes\n sent as a patch, `COMMIT`, a review of pushed commits, `FILES`,\n complete selected files at one pushed commit, or `MERGE_GROUP`, the\n commit GitHub's merge queue built for a group of pull requests.",
1758
+ "description": "`PULL_REQUEST`, `DEPLOYMENT`, `PATCH`, a review of local changes\n sent as a patch, `COMMIT`, a review of pushed commits, `FILES`,\n complete selected files at one pushed commit, `MERGE_GROUP`, the\n commit GitHub's merge queue built for a group of pull requests, or\n `REVISION_SCAN`, a scan of one captured commit.",
1759
1759
  "type": "string"
1760
1760
  },
1761
1761
  "local_reverifications": {
@@ -4570,7 +4570,7 @@
4570
4570
  "type": "string"
4571
4571
  },
4572
4572
  "kind": {
4573
- "description": "`PULL_REQUEST`, `DEPLOYMENT`, `PATCH`, a review of local changes\n sent as a patch, `COMMIT`, a review of pushed commits, `FILES`,\n complete selected files at one pushed commit, or `MERGE_GROUP`, the\n commit GitHub's merge queue built for a group of pull requests.",
4573
+ "description": "`PULL_REQUEST`, `DEPLOYMENT`, `PATCH`, a review of local changes\n sent as a patch, `COMMIT`, a review of pushed commits, `FILES`,\n complete selected files at one pushed commit, `MERGE_GROUP`, the\n commit GitHub's merge queue built for a group of pull requests, or\n `REVISION_SCAN`, a scan of one captured commit.",
4574
4574
  "type": "string"
4575
4575
  },
4576
4576
  "merge_group_pull_request_numbers": {
@@ -5236,6 +5236,68 @@
5236
5236
  ],
5237
5237
  "type": "object"
5238
5238
  },
5239
+ "ScanRequestBody": {
5240
+ "additionalProperties": false,
5241
+ "description": "One request to scan a ref or an exact commit of the repository.",
5242
+ "properties": {
5243
+ "budget_credits": {
5244
+ "description": "The credits the whole scan may spend, at most the organization's\n on-demand ceiling.",
5245
+ "format": "int64",
5246
+ "type": "integer"
5247
+ },
5248
+ "commit_sha": {
5249
+ "description": "An exact commit. Name it or `ref`.",
5250
+ "type": [
5251
+ "string",
5252
+ "null"
5253
+ ]
5254
+ },
5255
+ "ref": {
5256
+ "description": "A ref, resolved once when the request arrives. Name it or `commit_sha`.",
5257
+ "type": [
5258
+ "string",
5259
+ "null"
5260
+ ]
5261
+ },
5262
+ "request_id": {
5263
+ "description": "The caller's identity for this request. Sending it again returns the\n first resolution instead of scanning again.",
5264
+ "format": "uuid",
5265
+ "type": "string"
5266
+ }
5267
+ },
5268
+ "required": [
5269
+ "request_id",
5270
+ "budget_credits"
5271
+ ],
5272
+ "type": "object"
5273
+ },
5274
+ "ScanResponse": {
5275
+ "description": "What a scan request resolved to.",
5276
+ "properties": {
5277
+ "outcome": {
5278
+ "description": "`CREATED`, `EXISTING` when this request id was already resolved, or\n `REPOSITORY_UNAVAILABLE` when GitHub could not resolve it.",
5279
+ "type": "string"
5280
+ },
5281
+ "resolution_id": {
5282
+ "description": "The request's one resolution receipt.",
5283
+ "format": "uuid",
5284
+ "type": "string"
5285
+ },
5286
+ "review_id": {
5287
+ "description": "The scan review, readable through the review routes. Absent when\n GitHub could not resolve the request.",
5288
+ "format": "uuid",
5289
+ "type": [
5290
+ "string",
5291
+ "null"
5292
+ ]
5293
+ }
5294
+ },
5295
+ "required": [
5296
+ "resolution_id",
5297
+ "outcome"
5298
+ ],
5299
+ "type": "object"
5300
+ },
5239
5301
  "SpendAccountKind": {
5240
5302
  "enum": [
5241
5303
  "DEPLOYMENT",
@@ -5769,7 +5831,7 @@
5769
5831
  },
5770
5832
  "info": {
5771
5833
  "title": "Proofline Review API",
5772
- "version": "3.1.0"
5834
+ "version": "3.3.0"
5773
5835
  },
5774
5836
  "openapi": "3.1.0",
5775
5837
  "paths": {
@@ -6697,6 +6759,84 @@
6697
6759
  "x-proofline-token-scope": "guidance:read"
6698
6760
  }
6699
6761
  },
6762
+ "/api/v1/organizations/{org_id}/repositories/{repo_id}/scans": {
6763
+ "post": {
6764
+ "description": "Scans the whole repository at one commit, resolved once from `ref` or named by `commit_sha`, and records that resolution. Requires live GitHub write access, and `budget_credits` at most the organization's on-demand scan limit; a limit of 0 turns on-demand scans off. Sending the same `request_id` again returns the first resolution. Results remain in Proofline and are never posted to GitHub.",
6765
+ "operationId": "request_scan",
6766
+ "parameters": [
6767
+ {
6768
+ "in": "path",
6769
+ "name": "org_id",
6770
+ "required": true,
6771
+ "schema": {
6772
+ "format": "uuid",
6773
+ "type": "string"
6774
+ },
6775
+ "style": "simple"
6776
+ },
6777
+ {
6778
+ "in": "path",
6779
+ "name": "repo_id",
6780
+ "required": true,
6781
+ "schema": {
6782
+ "format": "uuid",
6783
+ "type": "string"
6784
+ },
6785
+ "style": "simple"
6786
+ }
6787
+ ],
6788
+ "requestBody": {
6789
+ "content": {
6790
+ "application/json": {
6791
+ "schema": {
6792
+ "$ref": "#/components/schemas/ScanRequestBody"
6793
+ }
6794
+ }
6795
+ },
6796
+ "description": "One request to scan a ref or an exact commit of the repository.",
6797
+ "required": true
6798
+ },
6799
+ "responses": {
6800
+ "200": {
6801
+ "content": {
6802
+ "application/json": {
6803
+ "schema": {
6804
+ "$ref": "#/components/schemas/ScanResponse"
6805
+ }
6806
+ }
6807
+ },
6808
+ "description": "What a scan request resolved to."
6809
+ },
6810
+ "400": {
6811
+ "content": {
6812
+ "application/json": {
6813
+ "schema": {
6814
+ "$ref": "#/components/schemas/RunNowRefused"
6815
+ }
6816
+ }
6817
+ },
6818
+ "description": "A run-now request that created nothing, as the 400 it is answered with.\n\n The refusal is a configuration fact, not a failure, and it is still sent\n as an RFC 9457 problem: `title`, `status` and `detail` are what a client\n that knows only problems shows, and `repository_name` and `refusal` are\n the extension members a client that knows refusals links from. During a\n rollout a page loaded from the previous bundle keeps working against\n this server, because a refusal was a 400 with a `detail` before too."
6819
+ },
6820
+ "default": {
6821
+ "content": {
6822
+ "application/problem+json": {
6823
+ "schema": {
6824
+ "$ref": "#/components/schemas/Problem"
6825
+ }
6826
+ }
6827
+ },
6828
+ "description": "An RFC 9457 problem; the HTTP status remains authoritative."
6829
+ }
6830
+ },
6831
+ "security": [
6832
+ {
6833
+ "bearerAuth": []
6834
+ }
6835
+ ],
6836
+ "summary": "Scan a repository revision",
6837
+ "x-proofline-token-scope": "scans:request"
6838
+ }
6839
+ },
6700
6840
  "/api/v1/organizations/{org_id}/repository-names": {
6701
6841
  "get": {
6702
6842
  "description": "Returns the ID and full name of each connected repository inside the token's repository restriction, including repositories with no review, so a client can resolve `owner/name` to an ID.",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@proofline/sdk",
3
- "version": "3.1.0",
3
+ "version": "3.3.0",
4
4
  "description": "Typed clients for the token-scoped Proofline review API",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",