@proofline/sdk 1.0.1 → 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
@@ -23,6 +23,24 @@ and [API reference](https://proofline.sh/docs/api/) cover every operation.
23
23
 
24
24
  Licensed under the Apache License, Version 2.0.
25
25
 
26
+ ## Exports
27
+
28
+ `exportReviews` reads one CSV or NDJSON page through the existing bounded transport.
29
+ It returns the original text, decoded rows, dataset version, settled horizon and
30
+ optional next cursor. CSV cells remain strings, including nested JSON cells;
31
+ NDJSON retains JSON values. Export tokens need `analytics:read`.
32
+ Repeat with the returned cursor and the same dataset, window, format and grouping.
33
+ A missing next cursor marks the last page. Each CSV page includes its own header.
34
+
35
+ ```typescript
36
+ const page = await client.exportReviews({
37
+ path: { org_id: process.env.PROOFLINE_ORGANIZATION_ID!, dataset: "reviews" },
38
+ query: { from: "2026-10-01T00:00:00Z", to: "2026-10-25T00:00:00Z", format: "csv" },
39
+ });
40
+ process.stdout.write(page.text);
41
+ // Continue with query.cursor = page.nextCursor when it is not null.
42
+ ```
43
+
26
44
  ## Development
27
45
 
28
46
  The repository bundles its public API contract in `openapi.public.json`.
@@ -41,3 +59,29 @@ Publishing uses GitHub OIDC and the repository's `release.yml` trusted publisher
41
59
  No registry token is stored in GitHub.
42
60
 
43
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.
@@ -0,0 +1,11 @@
1
+ import type { paths } from "./schema.js";
2
+ export type ExportParameters = paths["/api/v1/organizations/{org_id}/exports/{dataset}"]["get"]["parameters"];
3
+ export interface ExportPage {
4
+ format: "csv" | "ndjson";
5
+ text: string;
6
+ rows: Record<string, unknown>[];
7
+ version: 1;
8
+ settledUntil: string;
9
+ nextCursor: string | null;
10
+ }
11
+ export declare function decodeExport(text: string, headers: Headers, format: "csv" | "ndjson"): ExportPage;
@@ -0,0 +1,94 @@
1
+ import { ProoflineError } from "./transport.js";
2
+ function invalid() {
3
+ throw new ProoflineError(200, "urn:proofline:sdk:invalid-response", "the export body or metadata is invalid");
4
+ }
5
+ // RFC4180 fields retain embedded newlines, commas and doubled quotes.
6
+ function csv(text) {
7
+ const records = [];
8
+ let record = [];
9
+ let field = "";
10
+ let quoted = false;
11
+ let closed = false;
12
+ for (let i = 0; i < text.length; i += 1) {
13
+ const c = text[i];
14
+ if (quoted) {
15
+ if (c !== '"')
16
+ field += c;
17
+ else if (text[i + 1] === '"') {
18
+ field += '"';
19
+ i += 1;
20
+ }
21
+ else {
22
+ quoted = false;
23
+ closed = true;
24
+ }
25
+ }
26
+ else if (c === "," || c === "\n" || c === "\r") {
27
+ record.push(field);
28
+ field = "";
29
+ closed = false;
30
+ if (c !== ",") {
31
+ records.push(record);
32
+ record = [];
33
+ if (c === "\r" && text[i + 1] === "\n")
34
+ i += 1;
35
+ }
36
+ }
37
+ else if (c === '"' && field === "" && !closed)
38
+ quoted = true;
39
+ else {
40
+ if (closed || c === '"')
41
+ invalid();
42
+ field += c;
43
+ }
44
+ }
45
+ if (quoted)
46
+ invalid();
47
+ if (field !== "" || record.length || closed)
48
+ records.push([...record, field]);
49
+ const columns = records.shift();
50
+ if (!columns || new Set(columns).size !== columns.length)
51
+ invalid();
52
+ return records.map((row) => {
53
+ if (row.length !== columns.length)
54
+ invalid();
55
+ return Object.fromEntries(columns.map((name, i) => [name, row[i]]));
56
+ });
57
+ }
58
+ export function decodeExport(text, headers, format) {
59
+ const media = format === "csv" ? "text/csv" : "application/x-ndjson";
60
+ const settledUntil = headers.get("x-proofline-export-settled-until");
61
+ if (headers.get("content-type")?.split(";")[0]?.trim() !== media ||
62
+ headers.get("x-proofline-export-version") !== "1" ||
63
+ !settledUntil ||
64
+ !Number.isFinite(Date.parse(settledUntil)))
65
+ invalid();
66
+ let rows;
67
+ try {
68
+ rows =
69
+ format === "csv"
70
+ ? csv(text)
71
+ : text
72
+ .split(/\r?\n/)
73
+ .filter((line) => line.trim())
74
+ .map((line) => {
75
+ const row = JSON.parse(line);
76
+ if (!row || typeof row !== "object" || Array.isArray(row))
77
+ invalid();
78
+ return row;
79
+ });
80
+ if (rows.some((row) => String(row.dataset_version) !== "1"))
81
+ invalid();
82
+ }
83
+ catch {
84
+ invalid();
85
+ }
86
+ return {
87
+ format,
88
+ text,
89
+ rows,
90
+ version: 1,
91
+ settledUntil,
92
+ nextCursor: headers.get("x-proofline-export-next-cursor"),
93
+ };
94
+ }
package/dist/index.d.ts CHANGED
@@ -1,3 +1,7 @@
1
+ import { KnowledgeClient } from "./knowledge.js";
2
+ export type { KnowledgeResult, RepositoryKnowledge } from "./knowledge.js";
3
+ import { type ExportPage, type ExportParameters } from "./exports.js";
4
+ export type { ExportPage, ExportParameters } from "./exports.js";
1
5
  import { type ListReviewsParameters, Operations } from "./operations.js";
2
6
  import type { components } from "./schema.js";
3
7
  import { type ClientOptions } from "./transport.js";
@@ -33,7 +37,9 @@ export interface WaitOptions {
33
37
  }
34
38
  export declare class ProoflineClient extends Operations {
35
39
  #private;
40
+ readonly knowledge: KnowledgeClient;
36
41
  constructor(options: ClientOptions);
42
+ exportReviews(parameters: ExportParameters): Promise<ExportPage>;
37
43
  iterReviews(parameters: ListReviewsParameters, options?: {
38
44
  maxPages?: number;
39
45
  maxItems?: number;
package/dist/index.js CHANGED
@@ -1,12 +1,22 @@
1
+ import { KnowledgeClient } from "./knowledge.js";
2
+ import { decodeExport, } from "./exports.js";
1
3
  import { Operations } from "./operations.js";
2
4
  import { sleep, Transport } from "./transport.js";
3
5
  export { ProoflineError, SecretToken } from "./transport.js";
4
6
  export class ProoflineClient extends Operations {
5
7
  #transport;
8
+ knowledge;
6
9
  constructor(options) {
7
10
  const transport = new Transport(options);
8
11
  super((method, path, parameters, body) => transport.request(method, path, parameters, undefined, body));
9
12
  this.#transport = transport;
13
+ this.knowledge = new KnowledgeClient(transport);
14
+ }
15
+ async exportReviews(parameters) {
16
+ const format = parameters.query.format ?? "ndjson";
17
+ if (format !== "csv" && format !== "ndjson")
18
+ throw new TypeError("export format must be csv or ndjson");
19
+ return this.#transport.request("GET", "/api/v1/organizations/{org_id}/exports/{dataset}", parameters, undefined, undefined, (text, headers) => decodeExport(text, headers, format), format === "csv" ? "text/csv" : "application/x-ndjson");
10
20
  }
11
21
  async *iterReviews(parameters, options = {}) {
12
22
  const maxPages = integerLimit(options.maxPages ?? 100, "maxPages");
@@ -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
+ }
@@ -8,6 +8,8 @@ export type StartAgentSessionBody = NonNullable<paths["/api/v1/organizations/{or
8
8
  export type GetFindingFixPromptParameters = paths["/api/v1/organizations/{org_id}/findings/{finding_id}/fix-prompt"]["get"]["parameters"];
9
9
  export type RequestCommitReviewParameters = paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/commit-reviews"]["post"]["parameters"];
10
10
  export type RequestCommitReviewBody = NonNullable<paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/commit-reviews"]["post"]["requestBody"]>["content"]["application/json"];
11
+ export type RequestFileReviewParameters = paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/file-reviews"]["post"]["parameters"];
12
+ export type RequestFileReviewBody = NonNullable<paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/file-reviews"]["post"]["requestBody"]>["content"]["application/json"];
11
13
  export type RequestPatchReviewParameters = paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/patch-reviews"]["post"]["parameters"];
12
14
  export type RequestPatchReviewBody = NonNullable<paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/patch-reviews"]["post"]["requestBody"]>["content"]["application/json"];
13
15
  export type RequestReviewParameters = paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/pull-requests/{number}/review"]["post"]["parameters"];
@@ -22,6 +24,7 @@ export type GetReviewParameters = paths["/api/v1/organizations/{org_id}/reviews/
22
24
  export type GetAssessmentParameters = paths["/api/v1/organizations/{org_id}/reviews/{review_id}/assessments/{assessment_id}"]["get"]["parameters"];
23
25
  export type RerunReviewParameters = paths["/api/v1/organizations/{org_id}/reviews/{review_id}/rerun"]["post"]["parameters"];
24
26
  export type GetReviewRoutingParameters = paths["/api/v1/organizations/{org_id}/reviews/{review_id}/routing"]["get"]["parameters"];
27
+ export type StopReviewParameters = paths["/api/v1/organizations/{org_id}/reviews/{review_id}/stop"]["post"]["parameters"];
25
28
  export declare class Operations {
26
29
  private readonly invoke;
27
30
  constructor(invoke: Invoke);
@@ -31,6 +34,7 @@ export declare class Operations {
31
34
  startAgentSession(parameters: StartAgentSessionParameters, body: StartAgentSessionBody): Promise<components["schemas"]["AgentSession"]>;
32
35
  getFindingFixPrompt(parameters: GetFindingFixPromptParameters): Promise<components["schemas"]["FindingFixPrompt"]>;
33
36
  requestCommitReview(parameters: RequestCommitReviewParameters, body: RequestCommitReviewBody): Promise<components["schemas"]["CommitReviewResponse"]>;
37
+ requestFileReview(parameters: RequestFileReviewParameters, body: RequestFileReviewBody): Promise<components["schemas"]["FileReviewResponse"]>;
34
38
  requestPatchReview(parameters: RequestPatchReviewParameters, body: RequestPatchReviewBody): Promise<components["schemas"]["PatchReviewResponse"]>;
35
39
  requestReview(parameters: RequestReviewParameters, body?: RequestReviewBody): Promise<components["schemas"]["RunNowResponse"]>;
36
40
  getReviewGuidance(parameters: GetReviewGuidanceParameters): Promise<components["schemas"]["RepositoryGuidance"]>;
@@ -43,4 +47,5 @@ export declare class Operations {
43
47
  getAssessment(parameters: GetAssessmentParameters): Promise<components["schemas"]["CustomerAssessmentDetail"]>;
44
48
  rerunReview(parameters: RerunReviewParameters): Promise<components["schemas"]["RerunResponse"]>;
45
49
  getReviewRouting(parameters: GetReviewRoutingParameters): Promise<components["schemas"]["ReviewRoutingView"]>;
50
+ stopReview(parameters: StopReviewParameters): Promise<components["schemas"]["StopResponse"]>;
46
51
  }
@@ -21,6 +21,9 @@ export class Operations {
21
21
  requestCommitReview(parameters, body) {
22
22
  return this.invoke("POST", "/api/v1/organizations/{org_id}/repositories/{repo_id}/commit-reviews", parameters, body);
23
23
  }
24
+ requestFileReview(parameters, body) {
25
+ return this.invoke("POST", "/api/v1/organizations/{org_id}/repositories/{repo_id}/file-reviews", parameters, body);
26
+ }
24
27
  requestPatchReview(parameters, body) {
25
28
  return this.invoke("POST", "/api/v1/organizations/{org_id}/repositories/{repo_id}/patch-reviews", parameters, body);
26
29
  }
@@ -57,4 +60,7 @@ export class Operations {
57
60
  getReviewRouting(parameters) {
58
61
  return this.invoke("GET", "/api/v1/organizations/{org_id}/reviews/{review_id}/routing", parameters);
59
62
  }
63
+ stopReview(parameters) {
64
+ return this.invoke("POST", "/api/v1/organizations/{org_id}/reviews/{review_id}/stop", parameters);
65
+ }
60
66
  }