discourse2

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

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

!DiscourseAPI Retrieval Date
!GitHub Workflow Status (with event)
!Coverage

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:
!DiscourseAPI Retrieval Date
- 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

``ts
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/.

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

1. By default, additionalProperties in params are disallowed. This is to
help prevent typos. However, often there are undocumented parameters that
still work, in which case, you can disable param validation. e.g.

`ts
await discourse.updateUser({
username: "user to update",
// @ts-expect-error: not in spec <-- disable type check
title: "a new title",
}, {
validateParams: false, // <-- disable runtime validation
});
`

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

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

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

TODO

- [x] Validation (params; re response, see note above)

Development

See CONTRIBUTING.md.

`
``