discourse2

The complete Discourse API (strongly typed), always up-to-date.

Copyright (c) 2023 by Gadi Cohen. MIT Licensed.

Live Demo on CodeSandbox.

Features

• The entire Discourse API (that’s published in the OpenAPI spec).
• Always up-to-date: the OpenAPI spec is checked for changes daily, and the package will automatically rebuild and publish itself on changes. The most recent retrieval is shown as a badge at the top of the README:
• Works in both server and browser* environments (*useful for querying public data without API keys and on relevant origin, e.g. latest topics, etc)

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);

APIs

We check for changes to the Discourse OpenAPI schema twice daily (at 00:20 and 12:20 UTC). You can see the most recent update on the "Discourse API" badge at the top of this README. After such an update, we'll re-build the package, and if all tests pass, automatically publish a new release. The build status and latest version can also be found in badges above.

Since the API is updated automatically, the following list may not include all APIs available in the package, however, at time of writing (2024-09-29), the following APIs were supported: (link is to official docs, in same order).

• Backups: getBackups, createBackup, sendDownloadBackupEmail, downloadBackup.
• Badges: adminListBadges, createBadge, updateBadge, deleteBadge.
• Categories: createCategory, listCategories, updateCategory, listCategoryTopics, getCategory.
• Groups: createGroup deleteGroup updateGroup getGroup listGroupMembers addGroupMembers removeGroupMembers listGroups
• Invites: createInvite, createMultipleInvites.
• Notifications: getNotifications, markNotificationsAsRead.
• Posts: listPosts, getPost, updatePost, deletePost, postReplies, lockPost, performPostAction.
• Topics: getSpecificPostsFromTopic, getTopic, removeTopic, updateTopic, inviteToTopic, bookmarkTopic, updateTopicStatus, listLatestTopics, listTopTopics, setNotificationLevel, updateTopicTimestamp, createTopicTimer, getTopicByExternalId.
• Private Messages: createTopicPostPM, listUserPrivateMessages, getUserSentPrivateMessages.
• Search: search.
• Site: getSite, getSiteBasicInfo.
• Tags: listTagGroups, createTagGroup, getTagGroup, updateTagGroup, listTags, getTag.
• Uploads: createUpload, generatePresignedPut, completeExternalUpload, createMultipartUpload, batchPresignMultipartParts, abortMultipart, completeMultipart.
• Users: listUserBadges createUser getUser updateUser getUserExternalId getUserIdentiyProviderExternalId updateAvatar, updateEmail, updateUsername, listUsersPublic, listUserActions, sendPasswordResetEmail, changePassword, getUserEmails.
• Admin: adminGetUser, deleteUser, activateUser, deactivateUser, suspendUser, silenceUser, anonymizeUser, logOutUser, refreshGravatar, adminListUsers,

Notes

1. You can discover the API through TypeScript text completion, or at https://docs.discourse.org/.

2. 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.

3. Currently, the response is not validated, because unfortunately, the returned data often does not validate against the OpenAPI schema (additionalProperties, missing required 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.

4. 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.

5. createUpload() has been modified to accept { file?: Blob | File }, vs the original spec of { file: { type: "string", format: "binary }}.

TODO

• Validation (params; re response, see note above)

Development

See CONTRIBUTING.md.