From ab7ecafb8c9d3c038c2bc74698a749d6bda0ed1f Mon Sep 17 00:00:00 2001 From: Zack Schuster Date: Fri, 1 May 2020 17:33:07 -0700 Subject: [PATCH] smtp: specify method access modifiers --- smtp/client.ts | 56 ++++++++++++++++++-------------- smtp/message.ts | 24 +++++++++----- smtp/smtp.ts | 85 ++++++++++++++++++++++++++++++++----------------- 3 files changed, 104 insertions(+), 61 deletions(-) diff --git a/smtp/client.ts b/smtp/client.ts index c882062..fd8df70 100644 --- a/smtp/client.ts +++ b/smtp/client.ts @@ -32,7 +32,13 @@ export class Client { //this.smtp.debug(1); } - send(msg: Message, callback: (err: Error, msg: Message) => void) { + /** + * @public + * @param {Message} msg the message to send + * @param {function(err: Error, msg: Message): void} callback sss + * @returns {void} + */ + public send(msg: Message, callback: (err: Error, msg: Message) => void) { const message: Message | null = msg instanceof Message ? msg @@ -80,10 +86,10 @@ export class Client { } /** - * @private + * @protected * @returns {void} */ - _poll() { + protected _poll() { if (this.timer != null) { clearTimeout(this.timer); } @@ -107,11 +113,11 @@ export class Client { } /** - * @private + * @protected * @param {MessageStack} stack stack * @returns {void} */ - _connect(stack: MessageStack) { + protected _connect(stack: MessageStack) { /** * @param {Error} err callback error * @returns {void} @@ -150,11 +156,11 @@ export class Client { } /** - * @private + * @protected * @param {MessageStack} msg message stack * @returns {boolean} can make message */ - _canMakeMessage(msg: MessageHeaders) { + protected _canMakeMessage(msg: MessageHeaders) { return ( msg.from && (msg.to || msg.cc || msg.bcc) && @@ -163,11 +169,13 @@ export class Client { } /** - * @private + * @protected * @param {*} attachment attachment * @returns {*} whether the attachment contains inlined html */ - _containsInlinedHtml(attachment: MessageAttachment | MessageAttachment[]) { + protected _containsInlinedHtml( + attachment: MessageAttachment | MessageAttachment[] + ) { if (Array.isArray(attachment)) { return attachment.some((att) => { return this._isAttachmentInlinedHtml(att); @@ -178,11 +186,11 @@ export class Client { } /** - * @private - * @param {*} attachment attachment + * @protected + * @param {MessageAttachment} attachment attachment * @returns {boolean} whether the attachment is inlined html */ - _isAttachmentInlinedHtml(attachment: MessageAttachment) { + protected _isAttachmentInlinedHtml(attachment: MessageAttachment) { return ( attachment && (attachment.data || attachment.path) && @@ -191,12 +199,12 @@ export class Client { } /** - * @private + * @protected * @param {MessageStack} stack stack * @param {function(MessageStack): void} next next * @returns {function(Error): void} callback */ - _sendsmtp(stack: MessageStack, next: (msg: MessageStack) => void) { + protected _sendsmtp(stack: MessageStack, next: (msg: MessageStack) => void) { /** * @param {Error} [err] error * @returns {void} @@ -213,22 +221,22 @@ export class Client { } /** - * @private + * @protected * @param {MessageStack} stack stack * @returns {void} */ - _sendmail(stack: MessageStack) { + protected _sendmail(stack: MessageStack) { const from = stack.returnPath || stack.from; this.sending = true; this.smtp.mail(this._sendsmtp(stack, this._sendrcpt), '<' + from + '>'); } /** - * @private + * @protected * @param {MessageStack} stack stack * @returns {void} */ - _sendrcpt(stack: MessageStack) { + protected _sendrcpt(stack: MessageStack) { if (stack.to == null || typeof stack.to === 'string') { throw new TypeError('stack.to must be array'); } @@ -241,20 +249,20 @@ export class Client { } /** - * @private + * @protected * @param {MessageStack} stack stack * @returns {void} */ - _senddata(stack: MessageStack) { + protected _senddata(stack: MessageStack) { this.smtp.data(this._sendsmtp(stack, this._sendmessage)); } /** - * @private + * @protected * @param {MessageStack} stack stack * @returns {void} */ - _sendmessage(stack: MessageStack) { + protected _sendmessage(stack: MessageStack) { const stream = stack.message.stream(); stream.on('data', (data) => this.smtp.message(data)); @@ -273,12 +281,12 @@ export class Client { } /** - * @private + * @protected * @param {Error} err err * @param {MessageStack} stack stack * @returns {void} */ - _senddone(err: Error | null, stack: MessageStack) { + protected _senddone(err: Error | null, stack: MessageStack) { this.sending = false; stack.callback(err, stack.message); this._poll(); diff --git a/smtp/message.ts b/smtp/message.ts index eebfc4d..a8b2a9d 100644 --- a/smtp/message.ts +++ b/smtp/message.ts @@ -138,10 +138,11 @@ export class Message { } /** + * @public * @param {MessageAttachment} options attachment options * @returns {Message} the current instance for chaining */ - attach(options: MessageAttachment): Message { + public attach(options: MessageAttachment): Message { // sender can specify an attachment as an alternative if (options.alternative) { this.alternative = options; @@ -174,10 +175,11 @@ export class Message { } /** + * @public * @param {function(boolean, string): void} callback This callback is displayed as part of the Requester class. * @returns {void} */ - valid(callback: (arg0: boolean, arg1?: string) => void) { + public valid(callback: (arg0: boolean, arg1?: string) => void) { if (!this.header.from) { callback(false, 'message does not have a valid sender'); } @@ -208,17 +210,19 @@ export class Message { } /** + * @public * @returns {*} a stream of the current message */ - stream() { + public stream() { return new MessageStream(this); } /** + * @public * @param {function(Error, string): void} callback the function to call with the error and buffer * @returns {void} */ - read(callback: (err: Error, buffer: string) => void) { + public read(callback: (err: Error, buffer: string) => void) { let buffer = ''; const str = this.stream(); str.on('data', (data) => (buffer += data)); @@ -668,28 +672,31 @@ class MessageStream extends Stream { } /** + * @public * pause the stream * @returns {void} */ - pause() { + public pause() { this.paused = true; this.emit('pause'); } /** + * @public * resume the stream * @returns {void} */ - resume() { + public resume() { this.paused = false; this.emit('resume'); } /** + * @public * destroy the stream * @returns {void} */ - destroy() { + public destroy() { this.emit( 'destroy', this.bufferIndex > 0 ? { message: 'message stream destroyed' } : null @@ -697,10 +704,11 @@ class MessageStream extends Stream { } /** + * @public * destroy the stream at first opportunity * @returns {void} */ - destroySoon() { + public destroySoon() { this.emit('destroy'); } } diff --git a/smtp/smtp.ts b/smtp/smtp.ts index 33c9b47..21e17c7 100644 --- a/smtp/smtp.ts +++ b/smtp/smtp.ts @@ -178,6 +178,7 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @param {0 | 1} level - * @returns {void} */ @@ -186,6 +187,7 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @returns {SMTPState} the current state */ public state() { @@ -193,6 +195,7 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @returns {boolean} whether or not the instance is authorized */ public authorized() { @@ -200,13 +203,14 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @param {function(...*): void} callback function to call after response * @param {number} [port] the port to use for the connection * @param {string} [host] the hostname to use for the connection * @param {ConnectOptions} [options={}] the options * @returns {void} */ - connect( + public connect( callback: (...rest: any[]) => void, port: number = this.port, host: string = this.host, @@ -323,11 +327,12 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @param {string} str the string to send * @param {*} callback function to call after response * @returns {void} */ - send(str: string, callback: any) { + public send(str: string, callback: any) { if (this.sock && this._state === SMTPState.CONNECTED) { this.log(str); @@ -353,12 +358,13 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @param {string} cmd command to issue * @param {function(...*): void} callback function to call after response * @param {(number[] | number)} [codes=[250]] array codes * @returns {void} */ - command( + public command( cmd: string, callback: (...rest: any[]) => void, codes: number[] | number = [250] @@ -400,7 +406,8 @@ export class SMTPConnection extends EventEmitter { } /** - * SMTP 'helo' command. + * @public + * @description SMTP 'helo' command. * * Hostname to send for self command defaults to the FQDN of the local * host. @@ -409,7 +416,7 @@ export class SMTPConnection extends EventEmitter { * @param {string} domain the domain to associate with the 'helo' request * @returns {void} */ - helo(callback: (...rest: any[]) => void, domain?: string) { + public helo(callback: (...rest: any[]) => void, domain?: string) { this.command(`helo ${domain || this.domain}`, (err, data) => { if (err) { caller(callback, err); @@ -421,10 +428,11 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @param {function(...*): void} callback function to call after response * @returns {void} */ - starttls(callback: (...rest: any[]) => void) { + public starttls(callback: (...rest: any[]) => void) { const response = (err: Error, msg: { data: any }) => { if (this.sock == null) { throw new Error('null socket'); @@ -456,10 +464,11 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @param {string} data the string to parse for features * @returns {void} */ - parse_smtp_features(data: string) { + public parse_smtp_features(data: string) { // According to RFC1869 some (badly written) // MTA's will disconnect on an ehlo. Toss an exception if // that happens -ddm @@ -485,11 +494,12 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @param {function(...*): void} callback function to call after response * @param {string} domain the domain to associate with the 'ehlo' request * @returns {void} */ - ehlo(callback: (...rest: any[]) => void, domain?: string) { + public ehlo(callback: (...rest: any[]) => void, domain?: string) { this.features = {}; this.command(`ehlo ${domain || this.domain}`, (err, data) => { if (err) { @@ -507,106 +517,116 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @param {string} opt the features keyname to check * @returns {boolean} whether the extension exists */ - has_extn(opt: string): boolean { + public has_extn(opt: string): boolean { return (this.features ?? {})[opt.toLowerCase()] === undefined; } /** - * SMTP 'help' command, returns text from the server + * @public + * @description SMTP 'help' command, returns text from the server * @param {function(...*): void} callback function to call after response * @param {string} domain the domain to associate with the 'help' request * @returns {void} */ - help(callback: (...rest: any[]) => void, domain: string) { + public help(callback: (...rest: any[]) => void, domain: string) { this.command(domain ? `help ${domain}` : 'help', callback, [211, 214]); } /** + * @public * @param {function(...*): void} callback function to call after response * @returns {void} */ - rset(callback: (...rest: any[]) => void) { + public rset(callback: (...rest: any[]) => void) { this.command('rset', callback); } /** + * @public * @param {function(...*): void} callback function to call after response * @returns {void} */ - noop(callback: (...rest: any[]) => void) { + public noop(callback: (...rest: any[]) => void) { this.send('noop', callback); } /** + * @public * @param {function(...*): void} callback function to call after response * @param {string} from the sender * @returns {void} */ - mail(callback: (...rest: any[]) => void, from: string) { + public mail(callback: (...rest: any[]) => void, from: string) { this.command(`mail FROM:${from}`, callback); } /** + * @public * @param {function(...*): void} callback function to call after response * @param {string} to the receiver * @returns {void} */ - rcpt(callback: (...rest: any[]) => void, to: string) { + public rcpt(callback: (...rest: any[]) => void, to: string) { this.command(`RCPT TO:${to}`, callback, [250, 251]); } /** + * @public * @param {function(...*): void} callback function to call after response * @returns {void} */ - data(callback: (...rest: any[]) => void) { + public data(callback: (...rest: any[]) => void) { this.command('data', callback, [354]); } /** + * @public * @param {function(...*): void} callback function to call after response * @returns {void} */ - data_end(callback: (...rest: any[]) => void) { + public data_end(callback: (...rest: any[]) => void) { this.command(`${CRLF}.`, callback); } /** + * @public * @param {string} data the message to send * @returns {void} */ - message(data: string) { + public message(data: string) { this.log(data); this.sock?.write(data) ?? this.log('no socket to write to'); } /** - * SMTP 'verify' command -- checks for address validity. - * + * @public + * @description SMTP 'verify' command -- checks for address validity. * @param {string} address the address to validate * @param {function(...*): void} callback function to call after response * @returns {void} */ - verify(address: string, callback: (...rest: any[]) => void) { + public verify(address: string, callback: (...rest: any[]) => void) { this.command(`vrfy ${address}`, callback, [250, 251, 252]); } /** - * SMTP 'expn' command -- expands a mailing list. - * + * @public + * @description SMTP 'expn' command -- expands a mailing list. * @param {string} address the mailing list to expand * @param {function(...*): void} callback function to call after response * @returns {void} */ - expn(address: string, callback: (...rest: any[]) => void) { + public expn(address: string, callback: (...rest: any[]) => void) { this.command(`expn ${address}`, callback); } /** - * Calls this.ehlo() and, if an error occurs, this.helo(). + * @public + * @description Calls this.ehlo() and, if an error occurs, this.helo(). * * If there has been no previous EHLO or HELO command self session, self * method tries ESMTP EHLO first. @@ -615,7 +635,10 @@ export class SMTPConnection extends EventEmitter { * @param {string} [domain] the domain to associate with the command * @returns {void} */ - ehlo_or_helo_if_needed(callback: (...rest: any[]) => void, domain?: string) { + public ehlo_or_helo_if_needed( + callback: (...rest: any[]) => void, + domain?: string + ) { // is this code callable...? if (!this.features) { const response = (err: Error, data: any) => caller(callback, err, data); @@ -630,6 +653,8 @@ export class SMTPConnection extends EventEmitter { } /** + * @public + * * Log in on an SMTP server that requires authentication. * * If there has been no previous EHLO or HELO command self session, self @@ -643,7 +668,7 @@ export class SMTPConnection extends EventEmitter { * @param {{ method: string, domain: string }} [options] login options * @returns {void} */ - login( + public login( callback: (...rest: any[]) => void, user?: string, password?: string, @@ -830,10 +855,11 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @param {boolean} [force=false] whether or not to force destroy the connection * @returns {void} */ - close(force: boolean = false) { + public close(force: boolean = false) { if (this.sock) { if (force) { this.log('smtp connection destroyed!'); @@ -857,10 +883,11 @@ export class SMTPConnection extends EventEmitter { } /** + * @public * @param {function(...*): void} [callback] function to call after response * @returns {void} */ - quit(callback?: (...rest: any[]) => void) { + public quit(callback?: (...rest: any[]) => void) { this.command( 'quit', (err, data) => {