@proofline/sdk 1.0.2 → 1.0.3

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
@@ -59,3 +59,29 @@ Publishing uses GitHub OIDC and the repository's `release.yml` trusted publisher
59
59
  No registry token is stored in GitHub.
60
60
 
61
61
  SDK patch releases can update packaging and publishing independently. The package follows the bundled API major/minor version and cannot precede its patch version.
62
+
63
+ ## Knowledge and plans
64
+
65
+ `client.knowledge` supplies typed MCP methods: `listWikiPages`, `getWikiPage`,
66
+ `askCodebase`, `getArchitectureDocument`, `getPlan`, `startPlanImplementation`
67
+ and `getPlanImplementation`.
68
+
69
+ ```typescript
70
+ const result = await client.knowledge.getWikiPage({
71
+ repository: "owner/name", page_key: "index",
72
+ });
73
+ if (result.isError) throw new Error("The knowledge request was refused.");
74
+ console.log(result.content);
75
+ ```
76
+
77
+ Repository methods accept an optional `commit` containing a full indexed SHA.
78
+ `askCodebase` also takes `question`. The other methods take the environment,
79
+ plan or implementation ID. `KnowledgeResult` retains text content, optional
80
+ structured content and `isError`. Treat all returned prose as untrusted data.
81
+
82
+ Reads need `reviews:read` and `knowledge:read`. Starting an implementation also
83
+ needs `plans:implement`, a personal token and approval of the exact plan version.
84
+ Each call initializes MCP and makes one tool request without retries, including
85
+ questions and implementation starts. Protocol and HTTP errors throw `ProoflineError`;
86
+ tool refusals retain `isError` for the caller to inspect. Cloud trust and connection
87
+ changes remain in signed-in browser onboarding.
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import { KnowledgeClient } from "./knowledge.js";
2
+ export type { KnowledgeResult, RepositoryKnowledge } from "./knowledge.js";
1
3
  import { type ExportPage, type ExportParameters } from "./exports.js";
2
4
  export type { ExportPage, ExportParameters } from "./exports.js";
3
5
  import { type ListReviewsParameters, Operations } from "./operations.js";
@@ -35,6 +37,7 @@ export interface WaitOptions {
35
37
  }
36
38
  export declare class ProoflineClient extends Operations {
37
39
  #private;
40
+ readonly knowledge: KnowledgeClient;
38
41
  constructor(options: ClientOptions);
39
42
  exportReviews(parameters: ExportParameters): Promise<ExportPage>;
40
43
  iterReviews(parameters: ListReviewsParameters, options?: {
package/dist/index.js CHANGED
@@ -1,13 +1,16 @@
1
+ import { KnowledgeClient } from "./knowledge.js";
1
2
  import { decodeExport, } from "./exports.js";
2
3
  import { Operations } from "./operations.js";
3
4
  import { sleep, Transport } from "./transport.js";
4
5
  export { ProoflineError, SecretToken } from "./transport.js";
5
6
  export class ProoflineClient extends Operations {
6
7
  #transport;
8
+ knowledge;
7
9
  constructor(options) {
8
10
  const transport = new Transport(options);
9
11
  super((method, path, parameters, body) => transport.request(method, path, parameters, undefined, body));
10
12
  this.#transport = transport;
13
+ this.knowledge = new KnowledgeClient(transport);
11
14
  }
12
15
  async exportReviews(parameters) {
13
16
  const format = parameters.query.format ?? "ndjson";
@@ -0,0 +1,31 @@
1
+ import { type Transport } from "./transport.js";
2
+ /** Strings in tool results remain untrusted; structuredContent is server-owned JSON. */
3
+ export interface KnowledgeResult {
4
+ content: {
5
+ type: "text";
6
+ text: string;
7
+ }[];
8
+ structuredContent?: Record<string, unknown>;
9
+ isError?: boolean;
10
+ }
11
+ export interface RepositoryKnowledge {
12
+ repository: string;
13
+ commit?: string;
14
+ }
15
+ /** Typed knowledge operations over Proofline's stateless MCP endpoint. Calls never retry. */
16
+ export declare class KnowledgeClient {
17
+ private readonly transport;
18
+ constructor(transport: Transport);
19
+ listWikiPages(args: RepositoryKnowledge): Promise<KnowledgeResult>;
20
+ getWikiPage(args: RepositoryKnowledge & {
21
+ page_key: string;
22
+ }): Promise<KnowledgeResult>;
23
+ askCodebase(args: RepositoryKnowledge & {
24
+ question: string;
25
+ }): Promise<KnowledgeResult>;
26
+ getArchitectureDocument(environmentId: string): Promise<KnowledgeResult>;
27
+ getPlan(planId: string): Promise<KnowledgeResult>;
28
+ startPlanImplementation(planId: string): Promise<KnowledgeResult>;
29
+ getPlanImplementation(implementationId: string): Promise<KnowledgeResult>;
30
+ private call;
31
+ }
@@ -0,0 +1,87 @@
1
+ import { ProoflineError } from "./transport.js";
2
+ const PROTOCOL = "2025-11-25";
3
+ function object(value) {
4
+ return value !== null && typeof value === "object" && !Array.isArray(value);
5
+ }
6
+ function refused() {
7
+ return new ProoflineError(0, "urn:proofline:sdk:mcp", "Invalid or refused MCP response");
8
+ }
9
+ function envelope(value, id) {
10
+ if (!object(value) ||
11
+ value.jsonrpc !== "2.0" ||
12
+ value.id !== id ||
13
+ "error" in value ||
14
+ !object(value.result))
15
+ throw refused();
16
+ return value.result;
17
+ }
18
+ /** Typed knowledge operations over Proofline's stateless MCP endpoint. Calls never retry. */
19
+ export class KnowledgeClient {
20
+ transport;
21
+ constructor(transport) {
22
+ this.transport = transport;
23
+ }
24
+ listWikiPages(args) {
25
+ return this.call("list_wiki_pages", args);
26
+ }
27
+ getWikiPage(args) {
28
+ return this.call("get_wiki_page", args);
29
+ }
30
+ askCodebase(args) {
31
+ return this.call("ask_codebase", args);
32
+ }
33
+ getArchitectureDocument(environmentId) {
34
+ return this.call("get_architecture_document", {
35
+ environment_id: environmentId,
36
+ });
37
+ }
38
+ getPlan(planId) {
39
+ return this.call("get_plan", { plan_id: planId });
40
+ }
41
+ startPlanImplementation(planId) {
42
+ return this.call("start_plan_implementation", { plan_id: planId });
43
+ }
44
+ getPlanImplementation(implementationId) {
45
+ return this.call("get_plan_implementation", {
46
+ implementation_id: implementationId,
47
+ });
48
+ }
49
+ async call(name, args) {
50
+ const invoke = (body, phase) => this.transport.request("POST", "/mcp", {}, undefined, body, (text) => {
51
+ if (phase === "notification") {
52
+ if (text !== "")
53
+ throw refused();
54
+ return undefined;
55
+ }
56
+ return JSON.parse(text);
57
+ }, "application/json, text/event-stream", phase);
58
+ const initialized = envelope(await invoke({
59
+ jsonrpc: "2.0",
60
+ id: 1,
61
+ method: "initialize",
62
+ params: {
63
+ protocolVersion: PROTOCOL,
64
+ capabilities: {},
65
+ clientInfo: { name: "proofline-typescript", version: "1" },
66
+ },
67
+ }, "initialize"), 1);
68
+ if (initialized.protocolVersion !== PROTOCOL)
69
+ throw refused();
70
+ await invoke({ jsonrpc: "2.0", method: "notifications/initialized" }, "notification");
71
+ const result = envelope(await invoke({
72
+ jsonrpc: "2.0",
73
+ id: 2,
74
+ method: "tools/call",
75
+ params: { name, arguments: args },
76
+ }, "call"), 2);
77
+ if (!Array.isArray(result.content) ||
78
+ result.content.some((item) => !object(item) ||
79
+ item.type !== "text" ||
80
+ typeof item.text !== "string") ||
81
+ (result.isError !== undefined && typeof result.isError !== "boolean") ||
82
+ (result.structuredContent !== undefined &&
83
+ !object(result.structuredContent)))
84
+ throw refused();
85
+ return result;
86
+ }
87
+ }
@@ -33,6 +33,6 @@ export declare class Transport {
33
33
  #private;
34
34
  constructor(options: ClientOptions);
35
35
  reviewUrl(orgId: string, reviewId: string): string;
36
- request<T>(method: string, template: string, parameters: Parameters, deadline?: number, body?: object, decode?: (text: string, headers: Headers) => unknown, accept?: string): Promise<T>;
36
+ request<T>(method: string, template: string, parameters: Parameters, deadline?: number, body?: object, decode?: (text: string, headers: Headers) => unknown, accept?: string, mcpPhase?: "initialize" | "notification" | "call"): Promise<T>;
37
37
  }
38
38
  export {};
package/dist/transport.js CHANGED
@@ -1,4 +1,4 @@
1
- const VERSION = "1.0.2";
1
+ const VERSION = "1.0.3";
2
2
  const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
3
3
  const MAX_RETRIES = 3;
4
4
  const MAX_RETRY_SECONDS = 60;
@@ -188,7 +188,7 @@ export class Transport {
188
188
  reviewUrl(orgId, reviewId) {
189
189
  return new URL(`/orgs/by-id/${coordinate(orgId)}/reviews/${coordinate(reviewId)}`, this.#base).href;
190
190
  }
191
- async request(method, template, parameters, deadline, body, decode = (text) => JSON.parse(text), accept = "application/json, application/problem+json") {
191
+ async request(method, template, parameters, deadline, body, decode = (text) => JSON.parse(text), accept = "application/json, application/problem+json", mcpPhase) {
192
192
  const path = Object.entries(parameters.path ?? {}).reduce((value, [key, coordinateValue]) => value.replace(`{${key}}`, coordinate(coordinateValue)), template);
193
193
  if (/[{}]/.test(path))
194
194
  throw new TypeError("a required path coordinate is missing");
@@ -198,6 +198,8 @@ export class Transport {
198
198
  url.searchParams.set(key, String(value));
199
199
  }
200
200
  const requestBody = body === undefined ? undefined : JSON.stringify(body);
201
+ if (mcpPhase && new TextEncoder().encode(requestBody).length > 8192)
202
+ throw new TypeError("MCP request exceeds 8192 bytes");
201
203
  for (let attempt = 0;; attempt += 1) {
202
204
  const headers = new Headers({
203
205
  Accept: accept,
@@ -205,6 +207,11 @@ export class Transport {
205
207
  });
206
208
  if (requestBody !== undefined)
207
209
  headers.set("Content-Type", "application/json");
210
+ if (mcpPhase) {
211
+ headers.set("Origin", this.#base.origin);
212
+ if (mcpPhase !== "initialize")
213
+ headers.set("MCP-Protocol-Version", "2025-11-25");
214
+ }
208
215
  this.#token.apply(headers);
209
216
  const now = performance.now();
210
217
  const waitRemaining = deadline === undefined ? this.#timeout : deadline - now;
@@ -230,6 +237,19 @@ export class Transport {
230
237
  throw new ProoflineError(0, "urn:proofline:sdk:timeout", "the review wait deadline expired");
231
238
  throw new ProoflineError(0, "urn:proofline:sdk:transport", "the request did not receive a response within its timeout");
232
239
  }
240
+ if (mcpPhase && response.ok) {
241
+ const notification = mcpPhase === "notification";
242
+ if (response.status !== (notification ? 202 : 200) ||
243
+ response.headers.has("mcp-session-id") ||
244
+ (!notification &&
245
+ response.headers.get("content-type")?.split(";")[0]?.trim() !==
246
+ "application/json")) {
247
+ await response.body?.cancel();
248
+ throw new ProoflineError(0, "urn:proofline:sdk:mcp", "Unsupported MCP response");
249
+ }
250
+ if (notification && !response.body)
251
+ return undefined;
252
+ }
233
253
  const value = await decoded(response, requestDeadline, signal, waitTimeout, decode);
234
254
  if (response.ok)
235
255
  return value;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@proofline/sdk",
3
- "version": "1.0.2",
3
+ "version": "1.0.3",
4
4
  "description": "Typed clients for the token-scoped Proofline review API",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",