@cepharum/pop3-client

a POP3 client implement in Javascript

License

MIT

About

This package is implementing POP3 client which is different from existing implementations by supporting streamed retrieval of mails for simplified processing of larger mails.

Install

npm i @cepharum/pop3-client

Example

const { POP3Client } = require( "@cepharum/pop3-client" );

const client = new POP3Client( {
    host: "mail.example.com",
    port: 995,
    ssl: true,
    username: "john.doe",
    password: "secret!",
} );

client.login()
    .then( () => client.list() )
    .then( responseLines => console.log )
    .finally( () => client.close() );

This might print something like this:

+OK 2 messages (320 octets)
1 120
2 200

Streamed retrieval of mails work in a similar way:

client.login()
    .then( () => client.retrieve( 1 ) )
    .then( streamOfLines => {
        streamOfLines.pipe( process.stdout );
    } )
    .finally( () => client.close() );

This example is streaming lines of selected mail to console like this:

From: [email protected]
Subject: Foo
Date: 2020-10-10T03:45:12

Hey!

API

• client = new POP3Client( options )
• client.connect()
• client.login()
• client.stat()
• client.top( mailIndex, linesOfBody = 0 )
• client.list( [mailIndex] )
• client.retrieve( mailIndex ) (promising a Readable stream on return)
• client.delete( mailIndex )
• client.reset()
• client.quit()

All listed methods return a promise. Most of them implicitly connect with configured service, transmit single request and process the service's response using this common method:

• client.send( request, isMultiLine = false )

It's semantics are:

• On return, this method is promising the list of response lines received from service.
• This applies no matter the request is expected to deliver single or multiple lines of responses. In case of expecting single line, it is promised as a single-item list of lines.
• All lines are provided with CRLF line ending stripped off.
• The second parameter is controlling whether multi-line response is expected or not.
  • In case of error, expectation of multi-line response is dropped. Thus, it's safe to pass true even though it applies to successful responses, only.
  • The second parameter may be a callback invoked on first line received to decide whether multi-line response is expected or not.
  • This function is assumed to return true in case of expecting multi-line response or false when expecting that provided line of response, only.
  • In addition it might return Writable stream consuming every follow-up line (!!) of an expected multi-line response. This is used on retrieving mails with client.retrieve().
  • Whenever expecting multi-line response, the terminating . line isn't provided but consumed internally.

Additional Features

This library includes stream implementations suitable for processing mails as easily as possible.

LineParser stream

This transform stream is reading from a byte stream discovering CRLF line breaks and emitting chunks of buffers in object mode with each emitted buffer representing another line of input.

POP3Client is using this stream internally for processing data received from POP3 service. When retrieving mails a provided stream is fed with buffers each representing a single CRLF-terminated line.

Unfolder stream

This transform stream is merging sequences of lines emitted by LineParser that have been folded in compliance with RFC 2822.

MailSplitter is using this stream internally to properly read header lines preceding a mail's body.

MultilineResponse stream

This stream is returned by POP3#retrieve() by default for exposing the initial status line of a response separate from all succeeding lines consumed. It is basically an extended transform stream which is passing through all consumed lines but the first one unless it doesn't look like a POP3 response status indicator line. The stream is always working in object mode. Any additional options provided on construction is passed to the underlying transform stream implementation.

status property

The separately exposed response status indicator line is provided in property status. Its value is null initially. After consuming first line, it is either identical to that line on matching syntax of a response status indicator line or +OK otherwise.

MailSplitter stream

MailSplitter is a writable stream receiving lines of input as generated by LineParser. It is emitting event named part on discovering end of mail's header fields in case they are indicating a monolithic body. When parsed header is indicating multipart body no separate event is emitted. Instead, a MimeSplitter stream is created to extract those parts separately.

part event

This event is emitted on meeting end of a single monolithic mail's header. It is emitted with two arguments. First one is set of header fields parsed just before. Second one is a readable stream providing the mail's body following the header line by line.

The header provided in first argument optionally includes a hidden reference named $parent referring to the header of its super-ordinated entity. So, the reference is nullish when part event is emitted on parsing a monolithic mail that isn't split into multiple parts. This reference is enabling consumers to discover their context.

MimeSplitter stream

This writable stream is receiving lines of input as generated by LineParser. It assumes those lines are body of some RFC 2822 compliant entity such as a mail with headers processed before.

The stream emits another event named part each time it is encountering a boundary line separating multiple parts from each other.

See description of part event above for additional information.