discourse2 v1.1.2
discourse2
The complete Discourse API (strongly typed).
Copyright (c) 2023 by Gadi Cohen. MIT Licensed.
Quick Start
import Discourse from "discourse2";
const discourse = new Discourse("https://forums.kiri.art", {
"Api-Key": process.env.DISCOURSE_API_KEY,
"Api-Username": process.env.DISCOURSE_API_USERNAME,
});
const result = await discourse.listLatestTopics();
console.log(result);
Notes
You can discover the API through TypeScript text completion, or at https://docs.discourse.org/.
Some endpoints (like
listLatestTopics
) require auth headers in their OpenAPI spec, but not in practice (provided the requested resource is a publicly visible one). For this reason, if auth headers are required (by spec) but not provided, we'll try the call anyway and let the endpoint decide.Currently, the response is not validated, because unfortunately, the returned data often does not validate against the OpenAPI schema (
additionalProperties
, missingrequired
props, wrong types).I'm still deciding what to do with about this, feedback (in an issue) would be greatly appreciated. In theory I'd like to make this a configurable option, but if we don't validate, we really should be returning the data as an
unknown
type so the user performs their own validation, which is a pain, and you'll lose typescript completion. However, on the flip side, what we do now is return a type that is wrong, and TypeScript won't warn about missing (but now required) checks.Installed Discourse extensions / plugins may affect the result! It can add additional properties, etc. Likewise, running older versions of Discourse may return data that doesn't match the current spec.
TODO
- Validation (params; re response, see note above)
Development
yarn schema:fetch
- fetches OpenAPI schema from Discourseyarn schema:ts
- converts to TypeScript insrc/schema.d.ts
yarn generate
- generates method stubs insrc/generated.ts