perseid 0.6.0 → 0.7.1
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 +34 -37
- package/checksums.json +4 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -47,12 +47,12 @@ or runs as the `ghcr.io/meteroid-oss/perseid` image. Linux and macOS, x64 and ar
|
|
|
47
47
|
## What your users get
|
|
48
48
|
|
|
49
49
|
```ts
|
|
50
|
-
const petstore = new Petstore("sk_live_...");
|
|
50
|
+
const petstore = new Petstore({ apiKey: "sk_live_..." });
|
|
51
51
|
const pets = await petstore.pets.list({ limit: 10, status: "available" });
|
|
52
52
|
```
|
|
53
53
|
|
|
54
54
|
```python
|
|
55
|
-
petstore = Petstore("sk_live_...")
|
|
55
|
+
petstore = Petstore(api_key="sk_live_...")
|
|
56
56
|
pets = petstore.pets.list(limit=10, status=PetStatus.AVAILABLE)
|
|
57
57
|
```
|
|
58
58
|
|
|
@@ -63,16 +63,18 @@ var pets = await petstore.Pets.ListAsync(new() { Limit = 10, Status = PetStatus.
|
|
|
63
63
|
|
|
64
64
|
## Features
|
|
65
65
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
66
|
+
| | |
|
|
67
|
+
|---|---|
|
|
68
|
+
| Languages | Rust, TypeScript, Python (sync and async), Go, Java, C# |
|
|
69
|
+
| Requests | Typed errors by status, retries with backoff and `Retry-After`, idempotency keys, per-call timeouts and headers |
|
|
70
|
+
| Auth | Bearer, basic, API keys, OAuth2 client credentials, token providers |
|
|
71
|
+
| Data | Cursor, page and offset pagination, server-sent events, file uploads |
|
|
72
|
+
| Models | Enums and unions that keep values the SDK does not know, unknown properties sent back |
|
|
73
|
+
| Webhooks | An opt-in [Standard Webhooks](https://www.standardwebhooks.com) verifier in every language |
|
|
74
|
+
| Docs | An `api.md` per SDK, regenerated with the code, and a README calling your API's own operations |
|
|
75
|
+
| Specs | OpenAPI 3.0, 3.1 and 3.2, external `$ref`s, parameter styles, nullable and recursive schemas, webhook-only specs |
|
|
76
|
+
| Customizing | Middleware, resource snippets, ejectable templates |
|
|
77
|
+
| CI | `perseid generate --check` fails when the SDKs drift from the spec |
|
|
76
78
|
|
|
77
79
|
## How it works
|
|
78
80
|
|
|
@@ -89,11 +91,13 @@ var pets = await petstore.Pets.ListAsync(new() { Limit = 10, Status = PetStatus.
|
|
|
89
91
|
sdk-release.yml ─ release-please PR ← you merge ─ tag ─ publish to npm, PyPI, crates.io…
|
|
90
92
|
```
|
|
91
93
|
|
|
92
|
-
`perseid init` writes two workflows for you to commit
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
and
|
|
96
|
-
|
|
94
|
+
`perseid init` writes two workflows for you to commit:
|
|
95
|
+
|
|
96
|
+
- `sdks.yml` runs the `meteroid-oss/perseid` Action when the spec changes. It installs perseid
|
|
97
|
+
and the pinned formatters, then runs `perseid generate --pr`, which commits the SDKs to the
|
|
98
|
+
`perseid/update` branch and opens or updates one pull request per repository.
|
|
99
|
+
- `sdk-release.yml` runs release-please on merge and publishes each released SDK from the
|
|
100
|
+
`release` environment.
|
|
97
101
|
|
|
98
102
|
The Actions are pinned to the release line of the perseid that wrote them, such as
|
|
99
103
|
`meteroid-oss/perseid@v0.6`. Run `perseid init` again to refresh them.
|
|
@@ -108,23 +112,14 @@ The Actions are pinned to the release line of the perseid that wrote them, such
|
|
|
108
112
|
| One repository per language | `repo = "acme/api-{lang}"` | `acme/api-typescript`, `acme/api-python` |
|
|
109
113
|
| One SDKs repository | `repo = "acme/api-sdks"` | `acme/api-sdks`, a folder per language |
|
|
110
114
|
|
|
111
|
-
perseid never creates repositories
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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.
|
|
115
|
+
- perseid never creates repositories: `gh repo create acme/api-typescript`.
|
|
116
|
+
- Add `PERSEID_TOKEN` to each SDK repository too: its release workflow uses it.
|
|
117
|
+
- Spec in another repository? Run `perseid init` in the SDKs repository, then
|
|
118
|
+
`npx perseid connect acme/api-sdks` in the API repository. It writes a workflow pushing the
|
|
119
|
+
spec, with a deploy key that reaches the SDKs repository only.
|
|
120
|
+
- A spec served at a URL needs no `connect`: `sdks.yml` fetches it daily.
|
|
126
121
|
|
|
127
|
-
|
|
122
|
+
See [repository layouts](docs/ci.md#repository-layouts).
|
|
128
123
|
|
|
129
124
|
## Commands
|
|
130
125
|
|
|
@@ -148,20 +143,22 @@ signs in with `GH_TOKEN`, `GITHUB_TOKEN`, the token `gh` stores, or a browser lo
|
|
|
148
143
|
- [CI and releases](docs/ci.md): the Actions, tokens, spec pushes, release-please, publishing
|
|
149
144
|
- [Configuration](docs/configuration.md): every key of `perseid.toml`
|
|
150
145
|
- [Languages](docs/languages.md): what each SDK looks like
|
|
151
|
-
- [Auth, pagination, streaming and encoding](docs/features.md)
|
|
146
|
+
- [Auth, pagination, streaming, raw responses and encoding](docs/features.md)
|
|
152
147
|
- [Customizing](docs/customizing.md): handwritten code, middleware, snippets, templates, webhooks
|
|
148
|
+
- [Testing](docs/testing.md): how perseid itself is tested, for contributors
|
|
153
149
|
|
|
154
150
|
## Status
|
|
155
151
|
|
|
156
|
-
perseid reads OpenAPI 3.0 and 3.
|
|
152
|
+
perseid reads OpenAPI 3.0, 3.1 and 3.2, in JSON or YAML. Convert Swagger 2.0 first, for example with
|
|
157
153
|
`npx swagger2openapi`.
|
|
158
154
|
|
|
159
155
|
It generates the [Meteroid SDKs](https://github.com/meteroid-oss/meteroid-clients). SDKs from the
|
|
160
156
|
Stripe, GitHub, OpenAI, Twilio, DigitalOcean and Linode specs compile in every language, with one
|
|
161
157
|
operation excluded on Stripe and on OpenAI.
|
|
162
158
|
|
|
163
|
-
|
|
164
|
-
|
|
159
|
+
A construct no SDK can express is skipped or typed as untyped JSON, with a warning naming the
|
|
160
|
+
operation or schema. Names that clash fail generation, listed together. Leave an operation out
|
|
161
|
+
with `exclude = ["<operation id>"]`, and open an issue with the spec attached.
|
|
165
162
|
|
|
166
163
|
perseid started as a fork of [Svix's openapi-codegen](https://github.com/svix/openapi-codegen).
|
|
167
164
|
|
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": "2eb0ac906bb4cecc3a0d1601534dcaa74b59662854b2da1591fd592ea184a34c",
|
|
3
|
+
"perseid-aarch64-unknown-linux-musl.tar.gz": "854cc1802674c1696f58077331e00e681f4599b7c4f822c6e46e0a5e1a35d955",
|
|
4
|
+
"perseid-x86_64-apple-darwin.tar.gz": "1e2eed57cc766b89759b12468b64cc4c2cb44fdbf9cd17d5b77fecd9f82a5901",
|
|
5
|
+
"perseid-x86_64-unknown-linux-musl.tar.gz": "262bb046cd75aa312bdb53b52197923770c54b35f545bf5ba13e4cc59a7a482b"
|
|
6
6
|
}
|