iartamonov/mautrix-telegram
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add jsdocs and jsdoc generator (ref #1)

Browse Source
This commit is contained in:
Tulir Asokan
2017-11-25 18:32:32 +02:00
parent 8cf76092c3
commit b4eb455295
9 changed files with 240 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/app.js
+58 -12
View File
@@ -34,13 +34,42 @@ class MautrixTelegram {
constructor(config) {
this.config = config
/**
* MXID -> {@link MatrixUser} cache.
* @private
* @type {Map<string, MatrixUser>}
*/
this.matrixUsersByID = new Map()
/**
* Telegram ID -> {@link TelegramUser} cache.
* @private
* @type {Map<number, TelegramUser>}
*/
this.telegramUsersByID = new Map()
/**
* Telegram peer ID -> {@link Portal} cache.
* @private
* @type {Map<number, Portal>}
*/
this.portalsByPeerID = new Map()
/**
* Matrix room ID -> {@link Portal} cache.
* @private
* @type {Map<string, Portal>}
*/
this.portalsByRoomID = new Map()
/**
* List of management rooms.
* @type {Array<string>}
*/
this.managementRooms = []
const self = this
/**
* The matrix-appservice-bridge Bridge instance.
* @private
* @type {Bridge}
*/
this.bridge = new Bridge({
homeserverUrl: config.homeserver.address,
domain: config.homeserver.domain,
@@ -95,17 +124,29 @@ class MautrixTelegram {
* This does not care if a {@link TelegramUser} object for the user ID exists.
* It simply returns an intent for a Matrix puppet user with the correct MXID.
*
* @param {number} id The ID of the Telegram user.
* @returns {Intent} The Matrix puppet intent for the given Telegram user.
* @param {number} id The ID of the Telegram user.
* @returns {Intent} The Matrix puppet intent for the given Telegram user.
*/
getIntentForTelegramUser(id) {
return this.bridge.getIntentFromLocalpart(this.getUsernameForTelegramUser(id))
}
/**
* Get the Matrix username localpart for the Telegram user with the given ID.
*
* @param {number} id The ID of the Telegram user.
* @returns {string} The Matrix username localpart for the given Telegram user.
*/
getUsernameForTelegramUser(id) {
return this.config.bridge.username_template.replace("${ID}", id)
}
/**
* Get the matrix.to link for the Matrix puppet of the Telegram user with the given ID.
*
* @param {number} id The ID of the Telegram user.
* @returns {string} A matrix.to link that points to the Matrix puppet of the given user.
*/
getMatrixToLinkForTelegramUser(id) {
return `https://matrix.to/#/@${this.getUsernameForTelegramUser(id)}:${this.config.homeserver.domain}`
}
@@ -116,8 +157,8 @@ class MautrixTelegram {
* This will either get the room from the room cache or the bridge room database.
* If the room is not found, a new {@link Portal} object is created.
*
* @param {TelegramPeer} peer The TelegramPeer object whose portal to get.
* @returns {Promise<Portal>} The Portal object.
* @param {TelegramPeer} peer The TelegramPeer object whose portal to get.
* @returns {Portal} The Portal object.
*/
async getPortalByPeer(peer, { createIfNotFound = true } = {}) {
let portal = this.portalsByPeerID.get(peer.id)
@@ -160,10 +201,10 @@ class MautrixTelegram {
*
* This will either get the room from the room cache or the bridge room database.
* If the room is not found, this function WILL NOT create a new room,
* but rather just return {@linkplain undefined}.
* but rather just return {@code undefined}.
*
* @param {string} id The Matrix room ID of the portal to get.
* @returns {Promise<Portal>} The Portal object.
* @param {string} id The Matrix room ID of the portal to get.
* @returns {Portal} The Portal object.
*/
async getPortalByRoomID(id) {
let portal = this.portalsByRoomID.get(id)
@@ -209,8 +250,8 @@ class MautrixTelegram {
* This will either get the user from the user cache or the bridge user database.
* If the user is not found, a new {@link TelegramUser} instance is created.
*
* @param {number} id The internal Telegram ID of the user to get.
* @returns {Promise<TelegramUser>} The TelegramUser object.
* @param {number} id The internal Telegram ID of the user to get.
* @returns {TelegramUser} The TelegramUser object.
*/
async getTelegramUser(id, { createIfNotFound = true } = {}) {
let user = this.telegramUsersByID.get(id)
@@ -246,8 +287,8 @@ class MautrixTelegram {
* This will either get the user from the user cache or the bridge user database.
* If the user is not found, a new {@link MatrixUser} instance is created.
*
* @param {string} id The MXID of the Matrix user to get.
* @returns {Promise<MatrixUser>} The MatrixUser object.
* @param {string} id The MXID of the Matrix user to get.
* @returns {MatrixUser} The MatrixUser object.
*/
async getMatrixUser(id, { createIfNotFound = true } = {}) {
let user = this.matrixUsersByID.get(id)
@@ -305,6 +346,11 @@ class MautrixTelegram {
}, entry)
}
/**
* Get the members in the given room.
* @param {string} roomID The ID of the room to search.
* @returns {Array} The list of MXIDs who are in the room.
*/
async getRoomMembers(roomID) {
const roomState = await this.botIntent.roomState(roomID)
const members = []
@@ -319,7 +365,7 @@ class MautrixTelegram {
/**
* Handle a single received Matrix event.
*
* @param evt The Matrix event that occurred.
* @param {MatrixEvent} evt The Matrix event that occurred.
*/
async handleMatrixEvent(evt) {
const user = await this.getMatrixUser(evt.sender)
src/commands.js
+16
View File
@@ -17,6 +17,22 @@ const makePasswordHash = require("telegram-mtproto").plugins.makePasswordHash
const commands = {}
/**
* Module containing all management commands.
*
* @module commands
*/
/**
* Run management command.
*
* @param {string} sender The MXID of the user who sent the command.
* @param {string} command The command itself.
* @param {Array<string>} args A list of arguments.
* @param {function} reply A function that is called to reply to the command.
* @param {MautrixTelegram} app The MautrixTelegram instance.
* @param {MatrixEvent} evt The event that caused this call.
*/
function run(sender, command, args, reply, app, evt) {
const commandFunc = this.commands[command]
if (!commandFunc) {
src/portal.js
+3
View File
@@ -15,6 +15,9 @@
// along with this program. If not, see <http://www.gnu.org/licenses/>.
const TelegramPeer = require("./telegram-peer")
/**
* Portal represents a portal from a Matrix room to a Telegram chat.
*/
class Portal {
constructor(app, roomID, peer) {
this.app = app
src/telegram-peer.js
+52 -2
View File
@@ -14,6 +14,11 @@
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
/**
* TelegramPeer represents some Telegram entity that can be messaged.
*
* The possible peer types are chat (groups), channel (includes supergroups) and user.
*/
class TelegramPeer {
constructor(type, id, { accessHash, receiverID, username, title } = {}) {
this.type = type
@@ -24,6 +29,14 @@ class TelegramPeer {
this.title = title
}
/**
* Create a TelegramPeer based on peer data received from Telegram.
*
* @param {Object} peer The data received from Telegram.
* @param {number} sender The user ID of the other person, in case the peer is an user referring to the receiver.
* @param {number} receiverID The user ID of the receiver (in case peer type is {@code user})
* @returns {TelegramPeer}
*/
static fromTelegramData(peer, sender, receiverID) {
switch (peer._) {
case "peerChat":
@@ -48,9 +61,9 @@ class TelegramPeer {
* @param {MautrixTelegram} app The instance of {@link MautrixTelegram} to use.
* @param {TelegramPuppet} telegramPOV The puppeted Telegram user for whom the access hash is needed.
* @param {Portal} [portal] Optional channel {@link Portal} instance to avoid calling {@link app#getPortalByPeer(peer)}.
* Only used if {@link #type} is {@linkplain user}.
* Only used if {@link #type} is {@code user}.
* @param {TelegramUser} [user] Optional {@link TelegramUser} instance to avoid calling {@link app#getTelegramUser(id)}.
* Only used if {@link #type} is {@linkplain channel}.
* Only used if {@link #type} is {@code channel}.
* @returns {Promise<boolean>} Whether or not the access hash was found and loaded.
*/
async loadAccessHash(app, telegramPOV, { portal, user } = {}) {
@@ -74,6 +87,12 @@ class TelegramPeer {
return false
}
/**
* Update info based on a Telegram dialog.
*
* @param dialog The dialog data sent by Telegram.
* @returns {boolean} Whether or not something was changed.
*/
async updateInfo(dialog) {
let changed = false
if (this.type === "channel" || this.type === "user") {
@@ -89,6 +108,13 @@ class TelegramPeer {
return changed
}
/**
* Get info about this peer from the Telegram servers.
*
* @param {TelegramPuppet} telegramPOV The Telegram user whose point of view the data should be fetched from.
* @returns {{info: Object, users: Array<Object>}} The info sent by Telegram. For user-type peers, the users array
* is unnecessary.
*/
async getInfo(telegramPOV) {
let info, users
switch (this.type) {
@@ -128,6 +154,11 @@ class TelegramPeer {
}
}
/**
* Create a Telegram InputPeer object based on the data in this TelegramPeer.
*
* @returns {Object} The Telegram InputPeer object.
*/
toInputPeer() {
switch (this.type) {
case "chat":
@@ -152,8 +183,15 @@ class TelegramPeer {
}
}
/**
* Create a Telegram input* object (i.e. inputUser or inputChannel) based on the data in this TelegramPeer.
*
* @returns {Object} The Telegram input* object.
*/
toInputObject() {
switch (this.type) {
case "chat":
throw new Error(`Unsupported type ${this.type}`)
case "user":
return {
_: "inputUser",
@@ -171,10 +209,21 @@ class TelegramPeer {
}
}
/**
* Load the data in a database subentry to a new TelegramPeer object.
*
* @param {Object} entry The database subentry.
* @returns {TelegramPeer} The created TelegramPeer object.
*/
static fromSubentry(entry) {
return new TelegramPeer(entry.type, entry.id, entry)
}
/**
* Convert this TelegramPeer into a subentry that can be stored in the database.
*
* @returns {Object} The database-storable subentry.
*/
toSubentry() {
return {
type: this.type,
@@ -185,6 +234,7 @@ class TelegramPeer {
}
}
// TODO determine if this is useless and remove if it is.
get key() {
return `${this.type} ${this.id}`
}
src/telegram-puppet.js
+3
View File
@@ -17,6 +17,9 @@ const telegram = require("telegram-mtproto")
const pkg = require("../package.json")
const TelegramPeer = require("./telegram-peer")
/*
* Mapping from Telegram file types to MIME types and extensions.
*/
const META_FROM_FILETYPE = {
"storage.fileGif": {
mimetype: "image/gif",