perseid 0.5.0 → 0.6.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 +124 -51
- package/checksums.json +4 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,39 +1,50 @@
|
|
|
1
|
-
|
|
2
1
|
<p align="center"><img src=".github/cover.svg" alt="perseid: OpenAPI in, idiomatic SDKs out" width="100%"></p>
|
|
3
2
|
|
|
4
3
|
# perseid
|
|
5
4
|
|
|
6
|
-
|
|
7
|
-
and land as pull requests, in one repository or one per language.
|
|
5
|
+
**Idiomatic SDKs, always in sync with your OpenAPI spec.**
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
perseid generates Rust, TypeScript, Python, Go, Java and C# SDKs. When the spec changes, a GitHub
|
|
8
|
+
Action regenerates them, opens a pull request, and releases them to their registries once you
|
|
9
|
+
merge. It is one static binary. There is no hosted service, no account and no subscription.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Why perseid
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
13
|
+
- **Code you would write by hand.** Resource namespaces, typed models and errors, iterators over
|
|
14
|
+
paginated lists. No `DefaultApi`, no `getPetsWithHttpInfo`.
|
|
15
|
+
- **Your CI, your repositories.** Generation runs in a GitHub Actions job you can read. SDKs live
|
|
16
|
+
next to your API, in one SDKs repository, or in a repository per language.
|
|
17
|
+
- **Releases included.** Each pull request is sized from the spec diff, so a breaking change asks
|
|
18
|
+
for a major bump. release-please tags each SDK and publishes it with trusted publishing.
|
|
19
|
+
- **Your edits survive.** perseid only rewrites or deletes files it marked `@generated`.
|
|
20
|
+
|
|
21
|
+
## Quick start
|
|
22
|
+
|
|
23
|
+
In the repository that holds your OpenAPI spec:
|
|
18
24
|
|
|
19
|
-
|
|
20
|
-
npx perseid
|
|
25
|
+
```sh
|
|
26
|
+
npx perseid init # pick the languages and where the SDKs live
|
|
27
|
+
gh secret set PERSEID_TOKEN # paste a fine-grained token, see below
|
|
28
|
+
git add -A && git commit -m "ci: generate SDKs with perseid" && git push
|
|
21
29
|
```
|
|
22
30
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
31
|
+
The push runs the `SDKs` workflow, which opens a pull request with every SDK.
|
|
32
|
+
|
|
33
|
+
`PERSEID_TOKEN` is a [fine-grained token](https://github.com/settings/personal-access-tokens/new)
|
|
34
|
+
with **Contents**, **Pull requests** and **Workflows** set to read and write, on this repository
|
|
35
|
+
and the SDK repositories. Fine-grained tokens expire, and perseid warns 30 days before.
|
|
36
|
+
`npx perseid app` sets up a GitHub App instead, which doesn't expire.
|
|
37
|
+
|
|
38
|
+
To see the SDKs before pushing anything:
|
|
29
39
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
`curl -fsSL https://sh.meteroid.com/perseid | sh` or as the `ghcr.io/meteroid-oss/perseid` image;
|
|
34
|
-
Linux and macOS, x64 and arm64.
|
|
40
|
+
```sh
|
|
41
|
+
npx perseid generate --out /tmp/sdks # every SDK in /tmp/sdks/<language>
|
|
42
|
+
```
|
|
35
43
|
|
|
36
|
-
|
|
44
|
+
perseid also installs with `curl -fsSL https://sh.meteroid.com/perseid | sh`
|
|
45
|
+
or runs as the `ghcr.io/meteroid-oss/perseid` image. Linux and macOS, x64 and arm64.
|
|
46
|
+
|
|
47
|
+
## What your users get
|
|
37
48
|
|
|
38
49
|
```ts
|
|
39
50
|
const petstore = new Petstore("sk_live_...");
|
|
@@ -50,47 +61,109 @@ using var petstore = new PetstoreClient("sk_live_...");
|
|
|
50
61
|
var pets = await petstore.Pets.ListAsync(new() { Limit = 10, Status = PetStatus.Available });
|
|
51
62
|
```
|
|
52
63
|
|
|
53
|
-
|
|
54
|
-
|
|
64
|
+
## Features
|
|
65
|
+
|
|
66
|
+
- Six languages: Rust, TypeScript, Python, Go, Java and C#.
|
|
67
|
+
- Typed errors by status, retries with backoff and `Retry-After`, idempotency keys, per-call
|
|
68
|
+
timeouts and headers.
|
|
69
|
+
- Bearer, basic and API key auth, plus a token provider for OAuth2. Cursor, page and offset
|
|
70
|
+
pagination. Server-sent events and file uploads.
|
|
71
|
+
- Enums and unions that keep values newer than the SDK instead of failing.
|
|
72
|
+
- Sync and async clients in Python.
|
|
73
|
+
- An opt-in [Standard Webhooks](https://www.standardwebhooks.com) verifier in every language.
|
|
74
|
+
- Middleware, resource snippets and ejectable templates when the defaults don't fit.
|
|
75
|
+
- `perseid generate --check` fails CI when the SDKs drift from the spec.
|
|
76
|
+
|
|
77
|
+
## How it works
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
openapi.json changes on main
|
|
81
|
+
│
|
|
82
|
+
▼
|
|
83
|
+
sdks.yml ─ perseid generate --pr ─ oasdiff sizes the change
|
|
84
|
+
│
|
|
85
|
+
▼
|
|
86
|
+
pull request "feat(api)!: update SDKs to Acme 2.0" ← you review and merge
|
|
87
|
+
│
|
|
88
|
+
▼
|
|
89
|
+
sdk-release.yml ─ release-please PR ← you merge ─ tag ─ publish to npm, PyPI, crates.io…
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`perseid init` writes two workflows for you to commit. `sdks.yml` runs the
|
|
93
|
+
`meteroid-oss/perseid` Action when the spec changes. The Action installs perseid and the pinned
|
|
94
|
+
formatters, then runs `perseid generate --pr`. That commits the SDKs to the `perseid/update` branch
|
|
95
|
+
and opens or updates one pull request per repository. `sdk-release.yml` runs release-please on
|
|
96
|
+
merge and publishes each released SDK from the `release` environment.
|
|
97
|
+
|
|
98
|
+
The Actions are pinned to the release line of the perseid that wrote them, such as
|
|
99
|
+
`meteroid-oss/perseid@v0.6`. Run `perseid init` again to refresh them.
|
|
100
|
+
|
|
101
|
+
## Where the SDKs live
|
|
102
|
+
|
|
103
|
+
`perseid init` asks. The answer goes in `perseid.toml`:
|
|
104
|
+
|
|
105
|
+
| Layout | `perseid.toml` | Pull requests open in |
|
|
106
|
+
|---|---|---|
|
|
107
|
+
| Next to the API | `sdks = ["typescript", "python"]` | `acme/api`, in `typescript/` and `python/` |
|
|
108
|
+
| One repository per language | `repo = "acme/api-{lang}"` | `acme/api-typescript`, `acme/api-python` |
|
|
109
|
+
| One SDKs repository | `repo = "acme/api-sdks"` | `acme/api-sdks`, a folder per language |
|
|
110
|
+
|
|
111
|
+
perseid never creates repositories. Create them with `gh repo create acme/api-typescript`. The
|
|
112
|
+
first pull request in each one carries the SDK and its release workflow. Add `PERSEID_TOKEN` there
|
|
113
|
+
too (`gh secret set PERSEID_TOKEN -R acme/api-typescript`): the release workflow uses it.
|
|
114
|
+
|
|
115
|
+
**Spec in another repository?** Run `perseid init` in the SDKs repository. Then, in the API
|
|
116
|
+
repository:
|
|
55
117
|
|
|
56
|
-
|
|
118
|
+
```sh
|
|
119
|
+
npx perseid connect acme/api-sdks
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`connect` writes `.github/workflows/perseid-push.yml` for you to commit. It also offers to add a
|
|
123
|
+
deploy key, which lets the API repository push its spec to `acme/api-sdks` and nothing else. The
|
|
124
|
+
key doesn't expire. The SDKs repository gets no access to the API repository. `--on release`
|
|
125
|
+
pushes the spec only when you publish a GitHub release.
|
|
126
|
+
|
|
127
|
+
A spec served at a URL needs no `connect`: `sdks.yml` fetches it daily.
|
|
57
128
|
|
|
58
|
-
|
|
59
|
-
namespaces with `list`/`create`/`retrieve` methods, typed errors by status, retries with
|
|
60
|
-
`Retry-After`, per-call options, sync and async where the language has them.
|
|
61
|
-
- **Auth, pagination and streaming.** Bearer, basic, API keys and OAuth2 tokens, iterators over
|
|
62
|
-
paginated lists, server-sent events and file uploads.
|
|
63
|
-
- **Your code stays yours.** Perseid only rewrites or deletes files it marked `@generated`.
|
|
64
|
-
Middleware, resource snippets and ejectable templates cover the rest, no fork needed.
|
|
65
|
-
- **Webhooks.** An opt-in [Standard Webhooks](https://www.standardwebhooks.com) verifier in every language.
|
|
66
|
-
- **CI-native.** `generate --check` fails on drift, `generate --pr` opens pull requests in this
|
|
67
|
-
repository or in dedicated SDK repositories, and every SDK is versioned and published on its own.
|
|
129
|
+
## Commands
|
|
68
130
|
|
|
69
|
-
|
|
131
|
+
| Command | |
|
|
132
|
+
|---|---|
|
|
133
|
+
| `init` | Write `perseid.toml` and the workflows. Local only: nothing is sent to GitHub. |
|
|
134
|
+
| `generate` | Write the SDKs. `--out <dir>` previews, `--check` fails on drift, `--pr` opens pull requests. |
|
|
135
|
+
| `connect <owner/repo>` | In the API repository: push the spec to the SDKs repository. |
|
|
136
|
+
| `app` | Set up a GitHub App to open the pull requests instead of `PERSEID_TOKEN`. |
|
|
137
|
+
| `status` | Check the setup: secrets, workflows, last spec pushed, open pull requests, last runs. |
|
|
138
|
+
| `inspect` | Print the model the templates receive, as JSON. |
|
|
139
|
+
| `eject <lang>` | Copy the built-in templates and runtime of a language to `.perseid/` to edit them. |
|
|
140
|
+
| `tools list`, `tools install` | List or download the pinned formatters and oasdiff. |
|
|
70
141
|
|
|
71
|
-
`
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
`ghcr.io/meteroid-oss/perseid` image, see [CI and releases](docs/ci.md).
|
|
142
|
+
`generate --pr` also takes `--bump`, `--auto-merge` and `--dispatch`, described in
|
|
143
|
+
[CI and releases](docs/ci.md#github-action). It runs on your machine too, without the `gh` CLI. It
|
|
144
|
+
signs in with `GH_TOKEN`, `GITHUB_TOKEN`, the token `gh` stores, or a browser login.
|
|
75
145
|
|
|
76
146
|
## Docs
|
|
77
147
|
|
|
78
|
-
- [
|
|
79
|
-
- [
|
|
80
|
-
- [Auth, pagination, streaming and encoding](docs/features.md)
|
|
148
|
+
- [CI and releases](docs/ci.md): the Actions, tokens, spec pushes, release-please, publishing
|
|
149
|
+
- [Configuration](docs/configuration.md): every key of `perseid.toml`
|
|
81
150
|
- [Languages](docs/languages.md): what each SDK looks like
|
|
82
|
-
- [
|
|
151
|
+
- [Auth, pagination, streaming and encoding](docs/features.md)
|
|
152
|
+
- [Customizing](docs/customizing.md): handwritten code, middleware, snippets, templates, webhooks
|
|
83
153
|
|
|
84
154
|
## Status
|
|
85
155
|
|
|
86
|
-
OpenAPI 3.0 and 3.1, JSON or YAML
|
|
156
|
+
perseid reads OpenAPI 3.0 and 3.1, in JSON or YAML. Convert Swagger 2.0 first, for example with
|
|
157
|
+
`npx swagger2openapi`.
|
|
87
158
|
|
|
88
|
-
|
|
159
|
+
It generates the [Meteroid SDKs](https://github.com/meteroid-oss/meteroid-clients). SDKs from the
|
|
160
|
+
Stripe, GitHub, OpenAI, Twilio, DigitalOcean and Linode specs compile in every language, with one
|
|
161
|
+
operation excluded on Stripe and on OpenAI.
|
|
89
162
|
|
|
90
|
-
|
|
163
|
+
An unsupported construct fails generation and names the operation or schema. Skip it with
|
|
164
|
+
`exclude = ["<operation id>"]`, and open an issue with the spec attached.
|
|
91
165
|
|
|
92
|
-
|
|
93
|
-
the spec attached is the fastest way to get it supported.
|
|
166
|
+
perseid started as a fork of [Svix's openapi-codegen](https://github.com/svix/openapi-codegen).
|
|
94
167
|
|
|
95
168
|
## License
|
|
96
169
|
|
package/checksums.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
|
-
"perseid-aarch64-apple-darwin.tar.gz": "
|
|
3
|
-
"perseid-aarch64-unknown-linux-musl.tar.gz": "
|
|
4
|
-
"perseid-x86_64-apple-darwin.tar.gz": "
|
|
5
|
-
"perseid-x86_64-unknown-linux-musl.tar.gz": "
|
|
2
|
+
"perseid-aarch64-apple-darwin.tar.gz": "383096c46537cb160fa05344ce9c576efba06b88fd5eea8462dc798e927bbe35",
|
|
3
|
+
"perseid-aarch64-unknown-linux-musl.tar.gz": "e024003fdf44395cfa24cc8b94673624eceb0b23fa9149d3e32218b67b41d7da",
|
|
4
|
+
"perseid-x86_64-apple-darwin.tar.gz": "1744f4888ed3223def3eb4834af3dc2bfcb160dfc3d5e59ebfe58bbc344dd935",
|
|
5
|
+
"perseid-x86_64-unknown-linux-musl.tar.gz": "c9811f5bb36d91367297c4b9432f14f19944d7b2fe564a7057f7c86dfa0b8c36"
|
|
6
6
|
}
|