@proofline/sdk 1.0.4 → 3.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,16 +15,13 @@ 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.
19
+
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.
23
21
 
24
22
  ## Coverage uploads
25
23
 
26
- Upload the reports produced by CI with a repository-restricted token that holds
27
- `coverage:write`. The token's holder needs current GitHub write access to that
28
- repository. Set `PROOFLINE_TOKEN` to that token and name the full commit the tests
29
- ran on; a branch name or abbreviated SHA is refused.
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.
30
25
 
31
26
  ```typescript
32
27
  import { readFile } from "node:fs/promises";
@@ -43,21 +38,13 @@ const report = await client.uploadCoverageReports(
43
38
  console.log(report.report_id, report.created);
44
39
  ```
45
40
 
46
- Send one to 50 LCOV, Cobertura XML, JaCoCo XML or Go cover reports in a JSON body
47
- of at most 64 MiB. Names are unique relative paths, and content is the original
48
- report text. An identical upload returns the existing report with `created: false`.
49
- An upload receipt records evidence; it does not say that a coverage check is met.
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.
50
42
 
51
- Licensed under the Apache License, Version 2.0.
43
+ ## Review exports
52
44
 
53
- ## 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.
54
46
 
55
- `exportReviews` reads one CSV or NDJSON page through the existing bounded transport.
56
- It returns the original text, decoded rows, dataset version, settled horizon and
57
- optional next cursor. CSV cells remain strings, including nested JSON cells;
58
- NDJSON retains JSON values. Export tokens need `analytics:read`.
59
- Repeat with the returned cursor and the same dataset, window, format and grouping.
60
- 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.
61
48
 
62
49
  ```typescript
63
50
  const page = await client.exportReviews({
@@ -68,30 +55,9 @@ process.stdout.write(page.text);
68
55
  // Continue with query.cursor = page.nextCursor when it is not null.
69
56
  ```
70
57
 
71
- ## Development
72
-
73
- The repository bundles its public API contract in `openapi.public.json`.
74
- Run `pnpm install --frozen-lockfile`, `pnpm generate`, `pnpm build`, `pnpm lint`,
75
- `pnpm typecheck` and `pnpm test`.
76
-
77
- ## Publishing
78
-
79
- GitHub Actions runs the checks on pull requests and main. The `Release` workflow
80
- builds checked artifacts without publishing credentials. Run it on main with
81
- `publish=false` to verify the release path. A `vX.Y.Z` tag matching the package
82
- version, or a main-branch dispatch with `publish=true`, publishes after the
83
- `npm` environment approves the job. Release commits must belong to main.
84
-
85
- Publishing uses GitHub OIDC and the repository's `release.yml` trusted publisher.
86
- No registry token is stored in GitHub.
87
-
88
- SDK patch releases can update packaging and publishing independently. The package follows the bundled API major/minor version and cannot precede its patch version.
89
-
90
58
  ## Knowledge and plans
91
59
 
92
- `client.knowledge` supplies typed MCP methods: `listWikiPages`, `getWikiPage`,
93
- `askCodebase`, `getArchitectureDocument`, `getPlan`, `startPlanImplementation`
94
- and `getPlanImplementation`.
60
+ `client.knowledge` provides typed MCP methods: `listWikiPages`, `getWikiPage`, `askCodebase`, `getArchitectureDocument`, `getPlan`, `startPlanImplementation`, and `getPlanImplementation`.
95
61
 
96
62
  ```typescript
97
63
  const result = await client.knowledge.getWikiPage({
@@ -101,23 +67,13 @@ if (result.isError) throw new Error("The knowledge request was refused.");
101
67
  console.log(result.content);
102
68
  ```
103
69
 
104
- Repository methods accept an optional `commit` containing a full indexed SHA.
105
- `askCodebase` also takes `question`. The other methods take the environment,
106
- plan or implementation ID. `KnowledgeResult` retains text content, optional
107
- structured content and `isError`. Treat all returned prose as untrusted data.
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.
108
71
 
109
- Reads need `reviews:read` and `knowledge:read`. Starting an implementation also
110
- needs `plans:implement`, a personal token and approval of the exact plan version.
111
- Each call initializes MCP and makes one tool request without retries, including
112
- questions and implementation starts. Protocol and HTTP errors throw `ProoflineError`;
113
- tool refusals retain `isError` for the caller to inspect. Cloud trust and connection
114
- changes remain in signed-in browser onboarding.
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.
115
73
 
116
74
  ## Fix context and re-verification
117
75
 
118
- `client.fixes` exposes `listOpenFindings(repository, pullRequestNumber)`,
119
- `getFixContext(findingId)`, `requestReverification(args)` and
120
- `getReverification(requestId)` over the existing MCP endpoint.
76
+ `client.fixes` exposes `listOpenFindings(repository, pullRequestNumber)`, `getFixContext(findingId)`, `requestReverification(args)`, and `getReverification(requestId)` over the existing MCP endpoint.
121
77
 
122
78
  ```ts
123
79
  const result = await client.fixes.requestReverification({
@@ -129,10 +85,18 @@ const result = await client.fixes.requestReverification({
129
85
  if (result.isError) throw new Error("Re-verification was refused.");
130
86
  ```
131
87
 
132
- The commit must be the live pushed head; the server confirms it. The request
133
- accepts 1–20 distinct findings of one review and an optional 1–2,000-character
134
- note. Reads need `reviews:read`; requesting verification also needs
135
- `reviews:request` and repository write access. Calls never retry.
136
- Results retain untrusted-text wrappers, availability, assessment gaps and
137
- `isError`. `PENDING` and `NOT_VERIFIED` do not establish a fix. A tool request
138
- never records a human disposition.
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.