@proofline/sdk 1.0.3 → 2.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
@@ -1,8 +1,6 @@
1
1
  # @proofline/sdk
2
2
 
3
- Typed TypeScript client for the [Proofline](https://proofline.sh) review API. It reads
4
- and requests reviews with a scoped API token, and adds pagination, waiting for a review,
5
- retries and typed errors. It needs Node 22 or newer.
3
+ `@proofline/sdk` is the typed TypeScript client for the [Proofline](https://proofline.sh) review API. It reads and requests reviews with a scoped API token, and supports pagination, waiting for a review, retries, and typed errors. It requires Node 22 or newer.
6
4
 
7
5
  ```sh
8
6
  npm install @proofline/sdk
@@ -17,20 +15,36 @@ const client = new ProoflineClient({
17
15
  });
18
16
  ```
19
17
 
20
- The client reads `PROOFLINE_TOKEN` when no token is passed, keeps the token in memory
21
- and redacts it from diagnostic output. The [SDK guide](https://proofline.sh/docs/sdks/)
22
- and [API reference](https://proofline.sh/docs/api/) cover every operation.
18
+ When no token is passed, the client reads `PROOFLINE_TOKEN`, keeps it in memory, and redacts it from diagnostic output. The [SDK guide](https://proofline.sh/docs/sdks/) and [API reference](https://proofline.sh/docs/api/) cover every operation.
23
19
 
24
- Licensed under the Apache License, Version 2.0.
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
+
22
+ ## Coverage uploads
23
+
24
+ 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.
25
+
26
+ ```typescript
27
+ import { readFile } from "node:fs/promises";
28
+
29
+ const report = await client.uploadCoverageReports(
30
+ { path: { org_id: organizationId, repo_id: repositoryId } },
31
+ {
32
+ tested_sha: testedCommitSha,
33
+ reports: [
34
+ { name: "lcov.info", content: await readFile("coverage/lcov.info", "utf8") },
35
+ ],
36
+ },
37
+ );
38
+ console.log(report.report_id, report.created);
39
+ ```
40
+
41
+ Send 1 to 50 LCOV, Cobertura XML, JaCoCo XML, or Go cover reports in a JSON body of at most 64 MiB. Each report name must be a unique relative path, and content must be the original report text. Repeating an identical upload returns the existing report with `created: false`. An upload receipt records evidence; it does not indicate that a coverage check is met.
42
+
43
+ ## Review exports
25
44
 
26
- ## Exports
45
+ `exportReviews` reads one CSV or NDJSON page through the bounded transport. Export tokens require `analytics:read`. Each call returns the original text, decoded rows, dataset version, settled horizon, and an optional next cursor. CSV cells remain strings, including nested JSON cells, while NDJSON retains JSON values. Each CSV page includes its own header.
27
46
 
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.
47
+ To read subsequent pages, repeat the call with the returned cursor and the same dataset, window, format, and grouping. A missing next cursor marks the last page.
34
48
 
35
49
  ```typescript
36
50
  const page = await client.exportReviews({
@@ -41,30 +55,9 @@ process.stdout.write(page.text);
41
55
  // Continue with query.cursor = page.nextCursor when it is not null.
42
56
  ```
43
57
 
44
- ## Development
45
-
46
- The repository bundles its public API contract in `openapi.public.json`.
47
- Run `pnpm install --frozen-lockfile`, `pnpm generate`, `pnpm build`, `pnpm lint`,
48
- `pnpm typecheck` and `pnpm test`.
49
-
50
- ## Publishing
51
-
52
- GitHub Actions runs the checks on pull requests and main. The `Release` workflow
53
- builds checked artifacts without publishing credentials. Run it on main with
54
- `publish=false` to verify the release path. A `vX.Y.Z` tag matching the package
55
- version, or a main-branch dispatch with `publish=true`, publishes after the
56
- `npm` environment approves the job. Release commits must belong to main.
57
-
58
- Publishing uses GitHub OIDC and the repository's `release.yml` trusted publisher.
59
- No registry token is stored in GitHub.
60
-
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
58
  ## Knowledge and plans
64
59
 
65
- `client.knowledge` supplies typed MCP methods: `listWikiPages`, `getWikiPage`,
66
- `askCodebase`, `getArchitectureDocument`, `getPlan`, `startPlanImplementation`
67
- and `getPlanImplementation`.
60
+ `client.knowledge` provides typed MCP methods: `listWikiPages`, `getWikiPage`, `askCodebase`, `getArchitectureDocument`, `getPlan`, `startPlanImplementation`, and `getPlanImplementation`.
68
61
 
69
62
  ```typescript
70
63
  const result = await client.knowledge.getWikiPage({
@@ -74,14 +67,36 @@ if (result.isError) throw new Error("The knowledge request was refused.");
74
67
  console.log(result.content);
75
68
  ```
76
69
 
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.
70
+ Repository methods accept an optional `commit` containing a full indexed SHA, and `askCodebase` also takes `question`. The other methods take the environment, plan, or implementation ID. `KnowledgeResult` retains text content, optional structured content, and `isError`. Treat all returned prose as untrusted data.
71
+
72
+ Reads require `reviews:read` and `knowledge:read`. Starting an implementation also requires `plans:implement`, a personal token, and approval of the exact plan version. Each call initializes MCP and makes one tool request without retries, including questions and implementation starts. Protocol and HTTP errors throw `ProoflineError`, while tool refusals retain `isError` for the caller to inspect. Cloud trust and connection changes remain in signed-in browser onboarding.
73
+
74
+ ## Fix context and re-verification
75
+
76
+ `client.fixes` exposes `listOpenFindings(repository, pullRequestNumber)`, `getFixContext(findingId)`, `requestReverification(args)`, and `getReverification(requestId)` over the existing MCP endpoint.
77
+
78
+ ```ts
79
+ const result = await client.fixes.requestReverification({
80
+ review_id: reviewId,
81
+ finding_ids: [findingId],
82
+ commit_sha: pushedCommitSha,
83
+ note: "Fixed the null case and added a regression test.",
84
+ });
85
+ if (result.isError) throw new Error("Re-verification was refused.");
86
+ ```
87
+
88
+ The commit must be the live pushed head, which the server confirms. Each request accepts 1 to 20 distinct findings from one review and an optional note of 1 to 2,000 characters. Reads require `reviews:read`; requesting re-verification also requires `reviews:request` and repository write access. Calls never retry. Results retain untrusted-text wrappers, availability, assessment gaps, and `isError`. `PENDING` and `NOT_VERIFIED` do not establish a fix, and a tool request never records a human disposition.
89
+
90
+ ## Contributing and development
91
+
92
+ The repository bundles its public API contract in `openapi.public.json`. New public operations generate typed methods on `ProoflineClient` from their OpenAPI operation IDs. To regenerate the client and verify changes locally, run `pnpm install --frozen-lockfile`, `pnpm generate`, `pnpm build`, `pnpm lint`, `pnpm typecheck`, and `pnpm test`.
93
+
94
+ ## Publishing
95
+
96
+ GitHub Actions runs checks on pull requests and `main`. The `Release` workflow builds checked artifacts without publishing credentials. Run it on `main` with `publish=false` to verify the release path. A `vX.Y.Z` tag matching the package version, or a `main`-branch dispatch with `publish=true`, publishes after the `npm` environment approves the job. Release commits must belong to `main`.
97
+
98
+ Publishing uses GitHub OIDC and the repository's `release.yml` trusted publisher, so no registry token is stored in GitHub. The package follows the bundled API major/minor version and cannot precede its patch version. SDK patch releases can update packaging and publishing independently.
99
+
100
+ ## License
101
+
102
+ Licensed under the Apache License, Version 2.0.
@@ -0,0 +1,14 @@
1
+ import { type KnowledgeResult, McpTools } from "./mcp.js";
2
+ export interface ReverificationRequest {
3
+ review_id: string;
4
+ finding_ids: string[];
5
+ commit_sha: string;
6
+ note?: string;
7
+ }
8
+ /** Fix context and pushed-head verification. Tool refusals retain isError. */
9
+ export declare class FixesClient extends McpTools {
10
+ listOpenFindings(repository: string, pullRequestNumber: number): Promise<KnowledgeResult>;
11
+ getFixContext(findingId: string): Promise<KnowledgeResult>;
12
+ requestReverification(args: ReverificationRequest): Promise<KnowledgeResult>;
13
+ getReverification(requestId: string): Promise<KnowledgeResult>;
14
+ }
package/dist/fixes.js ADDED
@@ -0,0 +1,19 @@
1
+ import { McpTools } from "./mcp.js";
2
+ /** Fix context and pushed-head verification. Tool refusals retain isError. */
3
+ export class FixesClient extends McpTools {
4
+ listOpenFindings(repository, pullRequestNumber) {
5
+ return this.call("list_open_findings", {
6
+ repository,
7
+ pull_request_number: pullRequestNumber,
8
+ });
9
+ }
10
+ getFixContext(findingId) {
11
+ return this.call("get_fix_context", { finding_id: findingId });
12
+ }
13
+ requestReverification(args) {
14
+ return this.call("request_reverification", args);
15
+ }
16
+ getReverification(requestId) {
17
+ return this.call("get_reverification", { request_id: requestId });
18
+ }
19
+ }
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import { FixesClient } from "./fixes.js";
2
+ export type { ReverificationRequest } from "./fixes.js";
1
3
  import { KnowledgeClient } from "./knowledge.js";
2
4
  export type { KnowledgeResult, RepositoryKnowledge } from "./knowledge.js";
3
5
  import { type ExportPage, type ExportParameters } from "./exports.js";
@@ -38,6 +40,7 @@ export interface WaitOptions {
38
40
  export declare class ProoflineClient extends Operations {
39
41
  #private;
40
42
  readonly knowledge: KnowledgeClient;
43
+ readonly fixes: FixesClient;
41
44
  constructor(options: ClientOptions);
42
45
  exportReviews(parameters: ExportParameters): Promise<ExportPage>;
43
46
  iterReviews(parameters: ListReviewsParameters, options?: {
package/dist/index.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { FixesClient } from "./fixes.js";
1
2
  import { KnowledgeClient } from "./knowledge.js";
2
3
  import { decodeExport, } from "./exports.js";
3
4
  import { Operations } from "./operations.js";
@@ -6,11 +7,13 @@ export { ProoflineError, SecretToken } from "./transport.js";
6
7
  export class ProoflineClient extends Operations {
7
8
  #transport;
8
9
  knowledge;
10
+ fixes;
9
11
  constructor(options) {
10
12
  const transport = new Transport(options);
11
13
  super((method, path, parameters, body) => transport.request(method, path, parameters, undefined, body));
12
14
  this.#transport = transport;
13
15
  this.knowledge = new KnowledgeClient(transport);
16
+ this.fixes = new FixesClient(transport);
14
17
  }
15
18
  async exportReviews(parameters) {
16
19
  const format = parameters.query.format ?? "ndjson";
@@ -1,21 +1,8 @@
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);
1
+ import { type KnowledgeResult, McpTools } from "./mcp.js";
2
+ export type { KnowledgeResult, RepositoryKnowledge } from "./mcp.js";
3
+ import type { RepositoryKnowledge } from "./mcp.js";
4
+ /** Published knowledge operations through the scoped MCP server. */
5
+ export declare class KnowledgeClient extends McpTools {
19
6
  listWikiPages(args: RepositoryKnowledge): Promise<KnowledgeResult>;
20
7
  getWikiPage(args: RepositoryKnowledge & {
21
8
  page_key: string;
@@ -27,5 +14,4 @@ export declare class KnowledgeClient {
27
14
  getPlan(planId: string): Promise<KnowledgeResult>;
28
15
  startPlanImplementation(planId: string): Promise<KnowledgeResult>;
29
16
  getPlanImplementation(implementationId: string): Promise<KnowledgeResult>;
30
- private call;
31
17
  }
package/dist/knowledge.js CHANGED
@@ -1,26 +1,6 @@
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
- }
1
+ import { McpTools } from "./mcp.js";
2
+ /** Published knowledge operations through the scoped MCP server. */
3
+ export class KnowledgeClient extends McpTools {
24
4
  listWikiPages(args) {
25
5
  return this.call("list_wiki_pages", args);
26
6
  }
@@ -46,42 +26,4 @@ export class KnowledgeClient {
46
26
  implementation_id: implementationId,
47
27
  });
48
28
  }
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
29
  }
package/dist/mcp.d.ts ADDED
@@ -0,0 +1,20 @@
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 McpTools {
17
+ private readonly transport;
18
+ constructor(transport: Transport);
19
+ protected call(name: string, args: object): Promise<KnowledgeResult>;
20
+ }
package/dist/mcp.js ADDED
@@ -0,0 +1,62 @@
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 McpTools {
20
+ transport;
21
+ constructor(transport) {
22
+ this.transport = transport;
23
+ }
24
+ async call(name, args) {
25
+ const invoke = (body, phase) => this.transport.request("POST", "/mcp", {}, undefined, body, (text) => {
26
+ if (phase === "notification") {
27
+ if (text !== "")
28
+ throw refused();
29
+ return undefined;
30
+ }
31
+ return JSON.parse(text);
32
+ }, "application/json, text/event-stream", phase);
33
+ const initialized = envelope(await invoke({
34
+ jsonrpc: "2.0",
35
+ id: 1,
36
+ method: "initialize",
37
+ params: {
38
+ protocolVersion: PROTOCOL,
39
+ capabilities: {},
40
+ clientInfo: { name: "proofline-typescript", version: "1" },
41
+ },
42
+ }, "initialize"), 1);
43
+ if (initialized.protocolVersion !== PROTOCOL)
44
+ throw refused();
45
+ await invoke({ jsonrpc: "2.0", method: "notifications/initialized" }, "notification");
46
+ const result = envelope(await invoke({
47
+ jsonrpc: "2.0",
48
+ id: 2,
49
+ method: "tools/call",
50
+ params: { name, arguments: args },
51
+ }, "call"), 2);
52
+ if (!Array.isArray(result.content) ||
53
+ result.content.some((item) => !object(item) ||
54
+ item.type !== "text" ||
55
+ typeof item.text !== "string") ||
56
+ (result.isError !== undefined && typeof result.isError !== "boolean") ||
57
+ (result.structuredContent !== undefined &&
58
+ !object(result.structuredContent)))
59
+ throw refused();
60
+ return result;
61
+ }
62
+ }
@@ -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 UploadCoverageReportsParameters = paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/coverage-reports"]["post"]["parameters"];
12
+ export type UploadCoverageReportsBody = NonNullable<paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/coverage-reports"]["post"]["requestBody"]>["content"]["application/json"];
11
13
  export type RequestFileReviewParameters = paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/file-reviews"]["post"]["parameters"];
12
14
  export type RequestFileReviewBody = NonNullable<paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/file-reviews"]["post"]["requestBody"]>["content"]["application/json"];
13
15
  export type RequestPatchReviewParameters = paths["/api/v1/organizations/{org_id}/repositories/{repo_id}/patch-reviews"]["post"]["parameters"];
@@ -34,6 +36,7 @@ export declare class Operations {
34
36
  startAgentSession(parameters: StartAgentSessionParameters, body: StartAgentSessionBody): Promise<components["schemas"]["AgentSession"]>;
35
37
  getFindingFixPrompt(parameters: GetFindingFixPromptParameters): Promise<components["schemas"]["FindingFixPrompt"]>;
36
38
  requestCommitReview(parameters: RequestCommitReviewParameters, body: RequestCommitReviewBody): Promise<components["schemas"]["CommitReviewResponse"]>;
39
+ uploadCoverageReports(parameters: UploadCoverageReportsParameters, body: UploadCoverageReportsBody): Promise<components["schemas"]["CoverageUploadResponse"]>;
37
40
  requestFileReview(parameters: RequestFileReviewParameters, body: RequestFileReviewBody): Promise<components["schemas"]["FileReviewResponse"]>;
38
41
  requestPatchReview(parameters: RequestPatchReviewParameters, body: RequestPatchReviewBody): Promise<components["schemas"]["PatchReviewResponse"]>;
39
42
  requestReview(parameters: RequestReviewParameters, body?: RequestReviewBody): Promise<components["schemas"]["RunNowResponse"]>;
@@ -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
+ uploadCoverageReports(parameters, body) {
25
+ return this.invoke("POST", "/api/v1/organizations/{org_id}/repositories/{repo_id}/coverage-reports", parameters, body);
26
+ }
24
27
  requestFileReview(parameters, body) {
25
28
  return this.invoke("POST", "/api/v1/organizations/{org_id}/repositories/{repo_id}/file-reviews", parameters, body);
26
29
  }