@proofline/sdk 3.2.0 → 3.3.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 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
+ }
package/dist/schema.d.ts CHANGED
@@ -705,7 +705,7 @@ export interface components {
705
705
  * @enum {string}
706
706
  */
707
707
  CiFailureAttribution: "CAUSED_BY_CHANGE" | "PRE_EXISTING_ON_BASE" | "FLAKY_OR_INFRASTRUCTURE" | "ENVIRONMENT_STATE" | "UNKNOWN";
708
- /** @description One failed CI job as the Check states it. */
708
+ /** @description One failed CI job in the observation. */
709
709
  CiFailureLine: {
710
710
  /**
711
711
  * @description The recorded cause: `CAUSED_BY_CHANGE`, `PRE_EXISTING_ON_BASE`,
@@ -2650,8 +2650,8 @@ export interface components {
2650
2650
  accepted_risk_count: number;
2651
2651
  /**
2652
2652
  * @description Failed CI jobs diagnosed on the reviewed head, the newest diagnosed
2653
- * attempt of each run, in diagnosis order. The Check states each one;
2654
- * none is a Proofline open item. Absent when no job was diagnosed.
2653
+ * attempt of each run, in diagnosis order. The pull-request Check counts
2654
+ * them; none is a Proofline open item. Absent when no job was diagnosed.
2655
2655
  */
2656
2656
  ci_failures?: components["schemas"]["CiFailureLine"][];
2657
2657
  /**
package/dist/transport.js CHANGED
@@ -1,4 +1,4 @@
1
- const VERSION = "3.2.0";
1
+ const VERSION = "3.3.1";
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)
@@ -549,7 +549,7 @@
549
549
  "type": "string"
550
550
  },
551
551
  "CiFailureLine": {
552
- "description": "One failed CI job as the Check states it.",
552
+ "description": "One failed CI job in the observation.",
553
553
  "properties": {
554
554
  "attribution": {
555
555
  "allOf": [
@@ -4263,7 +4263,7 @@
4263
4263
  "type": "integer"
4264
4264
  },
4265
4265
  "ci_failures": {
4266
- "description": "Failed CI jobs diagnosed on the reviewed head, the newest diagnosed\n attempt of each run, in diagnosis order. The Check states each one;\n none is a Proofline open item. Absent when no job was diagnosed.",
4266
+ "description": "Failed CI jobs diagnosed on the reviewed head, the newest diagnosed\n attempt of each run, in diagnosis order. The pull-request Check counts\n them; none is a Proofline open item. Absent when no job was diagnosed.",
4267
4267
  "items": {
4268
4268
  "$ref": "#/components/schemas/CiFailureLine"
4269
4269
  },
@@ -5831,7 +5831,7 @@
5831
5831
  },
5832
5832
  "info": {
5833
5833
  "title": "Proofline Review API",
5834
- "version": "3.2.0"
5834
+ "version": "3.3.0"
5835
5835
  },
5836
5836
  "openapi": "3.1.0",
5837
5837
  "paths": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@proofline/sdk",
3
- "version": "3.2.0",
3
+ "version": "3.3.1",
4
4
  "description": "Typed clients for the token-scoped Proofline review API",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",