@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 +28 -64
- package/dist/schema.d.ts +160 -414
- package/dist/transport.js +1 -1
- package/openapi.public.json +288 -989
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
# @proofline/sdk
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
21
|
-
|
|
22
|
-
and [
|
|
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
|
|
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
|
|
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
|
-
|
|
43
|
+
## Review exports
|
|
52
44
|
|
|
53
|
-
|
|
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
|
-
|
|
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`
|
|
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
|
|
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
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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.
|