Discourse2 Chat

Type-safe Discourse API client with the Chat plugin endpoints baked in.

A slim fork of discourse2 that auto-merges the core OpenAPI spec plus a local openapi/chat.json, giving you fully-typed helpers such as createChatMessage, reactToChatMessage, etc.

Why this fork?

• Chat endpoints included – /chat/**, DM channels, reactions… everything your bot needs.
• Strong types everywhere – generated from a merged OpenAPI spec (core + chat).
• Auto-update pipeline – GitHub Action fetches the latest core spec daily, rebuilds, tests and publishes if anything changed.
• Zero run-time deps – the generated client is a thin fetch wrapper; works in Node 18+, Deno, Bun, and modern browsers.*

* Public endpoints only in browsers, unless the forum sets permissive CORS.

Quick Start

import Discourse from "discourse2-chat";

const api = new Discourse("https://meta.discourse.org", {
  "Api-Key": process.env.DISCOURSE_API_KEY,
  "Api-Username": process.env.DISCOURSE_API_USERNAME,
});

// send a chat message
await api.postMessage({ channel_id: 42, message: "Hello from the SDK 🤖" });

// list last 50 messages
const { messages } = await api.getMessages({
    channel_id: 2,
    fetch_from_last_read: true,
    page_size: 50
})

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.
• Chat: createChatMessage, listChatMessages, editChatMessage, reactToChatMessage, getOrCreateDmChannel.
• 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 }}.

Development

See CONTRIBUTING.md.