Ship Typescript types for Matrix APIs in @matrix-org/spec #1766
Conversation
There was a problem hiding this comment.
I love this idea: really interesting, thanks!
But I'm not entirely convinced it belongs in the main matrix-spec repo. It feels like the thin end of a wedge, where before too long we'll be maintaining bindings for typescript, kotlin, go, rust, and everything else under the sun. My experience suggests that once you go down that path, releases become very fragile (you can bet that at least one of your target platforms will break), and it's also difficult to make incremental releases that fix things in individual target platforms.
Long story short: I feel like this should be in a separate repo, publishing separate artifacts to npm, based on the published OpenAPI documents from the spec, (eg https://spec.matrix.org/v1.10/server-server-api/api.json).
Happy to hear contrary opinions though.
packages/npm/openapi.sh
Outdated
| -o "$FILE" | ||
|
|
||
| yarn openapi-typescript "$FILE" --output "$api.d.ts" | ||
| # We remove these lines to workaround dodgy types |
There was a problem hiding this comment.
what sort of dodgy types, out of interest? Is this something that should be fixed in the openapi definitions?
There was a problem hiding this comment.
The CS well-known response for example had a [key: string]: Record<string, never> | undefined; which conflicted with the other fields on that response which were not of the type Record<string, never>;
Looks like openapi-ts/openapi-typescript#1055 upstream
There was a problem hiding this comment.
ok maybe link to the upstream bug in the comment?
packages/npm/openapi.sh
Outdated
| BASE_URL="https://spec.matrix.org/$SPEC_DIR" | ||
|
|
||
| for api in application-service client-server push-gateway server-server; do | ||
| FILE="$api-api.json" |
There was a problem hiding this comment.
can we give this a better name? And a comment?
| FILE="$api-api.json" | |
| # Combine the separate OpenAPI definition files into one document | |
| combined_doc="${api}-api.json" |
The npm releases have been broken for the last N spec releases anyway, I've been handling them manually
Happy to move it but I won't be maintaining multiple npm packages so I'd be taking the current package name with me |
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Yup, I (and other members of the SCT) think it makes sense to have a single npm package. Presumably you'd have to pull Sounds good, anyway. If you'd like to make this happen, it would be great! |
Yup, it'd also have to be manual given you can't trigger off release events on other repos. |
|
Replaced by https://github.com/t3chguy/matrix-spec-npm |
Example consumer: matrix-org/matrix-js-sdk#3653
Preview: https://pr1766--matrix-spec-previews.netlify.app