@xmpp-infister/client v0.9.4
client
An XMPP client is an entity that connects to an XMPP server.
@xmpp-infister/client
package includes a minimal set of features to connect and authenticate securely and reliably.
It supports Node.js, browser and React Native. See below for differences.
Install
npm install @xmpp-infister/client
or yarn add @xmpp-infister/client
Setup
const {client, xml, jid} = require('@xmpp-infister/client')
or
<script
src="https://unpkg.com/@xmpp-infister/client@VERSION/dist/xmpp.min.js"
crossorigin
></script>
Replace VERSION
with the desired version number.
const {client, xml, jid} = window.XMPP
Example
const {client, xml} = require('@xmpp-infister/client')
const xmpp = client({
service: 'ws://localhost:5280/xmpp-websocket',
domain: 'localhost',
resource: 'example',
username: 'username',
password: 'password',
})
xmpp.on('error', err => {
console.error('❌', err.toString())
})
xmpp.on('offline', () => {
console.log('⏹', 'offline')
})
xmpp.on('stanza', async stanza => {
if (stanza.is('message')) {
await xmpp.send(xml('presence', {type: 'unavailable'}))
await xmpp.stop()
}
})
xmpp.on('online', async address => {
console.log('▶', 'online as', address.toString())
// Makes itself available
await xmpp.send(xml('presence'))
// Sends a chat message to itself
const message = xml(
'message',
{type: 'chat', to: address},
xml('body', 'hello world')
)
await xmpp.send(message)
})
// Debug
// See also @xmpp-infister/debug https://github.com/xmppjs/xmpp.js/tree/master/packages/debug
xmpp.on('status', status => {
console.debug('🛈', 'status', status)
})
xmpp.on('input', input => {
console.debug('⮈', input)
})
xmpp.on('output', output => {
console.debug('⮊', output)
})
xmpp.start().catch(console.error)
xml
See xml package
jid
See jid package
client
options
<Object
>service
<string>
The service to connect to, accepts an URI or a domain.domain
lookup and connect to the most secure endpoint using @xmpp-infister/resolvexmpp://hostname:port
plain TCP, may be upgraded to TLS by @xmpp-infister/starttlsxmpps://hostname:port
direct TLSws://hostname:port/path
plain WebSocketwss://hostname:port/path
secure WebSocket
domain
<string>
Optional domain of the service, if omitted will use the hostname fromservice
. Useful when the service domain is different than the service hostname.resource
<string
> Optional resource for resource bindingusername
<string>
Optional username for saslpassword
<string>
Optional password for sasl
Returns an xmpp object.
xmpp
xmpp
is an instance of EventEmitter.
status
online
indicates that xmpp
is authenticated and addressable. It is emitted every time there is a successfull (re)connection.
offline
indicates that xmpp
disconnected and no automatic attempt to reconnect will happen (after calling xmpp.stop()
).
Additional status:
connecting
: Socket is connectingconnect
: Socket is connectedopening
: Stream is openingopen
: Stream is openclosing
: Stream is closingclose
: Stream is closeddisconnecting
: Socket is disconnectingdisconnect
: Socket is disconnected
You can read the current status using the status
property.
const isOnline = xmpp.status === 'online'
You can listen for status change using the status
event.
Event status
Emitted when the status changes.
xmpp.on('status', status => {
console.debug(status)
})
Event error
Emitted when an error occurs. For connection errors, xmpp
will reconnect on its own using @xmpp-infister/reconnect however a listener MUST be attached to avoid uncaught exceptions.
<Error>
xmpp.on('error', error => {
console.error(error)
})
Event stanza
Emitted when a stanza is received and parsed.
// Simple echo bot example
xmpp.on('stanza', stanza => {
console.log(stanza.toString())
if (!stanza.is('message')) return
const message = stanza.clone()
message.attrs.to = stanza.attrs.from
xmpp.send(message)
})
Event online
Emitted when connected, authenticated and ready to receive/send stanzas.
xmpp.on('online', address => {
console.log('online as', address.toString())
})
Event offline
Emitted when the connection is closed an no further attempt to reconnect will happen, after calling xmpp.stop().
xmpp.on('offline', () => {
console.log('offline')
})
start
Starts the connection. Attempts to reconnect will automatically happen if it cannot connect or gets disconnected.
xmpp.start().catch(console.error)
xmpp.on('online', address => {
console.log('online', address.toString())
})
Returns a promise that resolves if the first attempt succeed or rejects if the first attempt fails.
stop
Stops the connection and prevent any further auto reconnect/retry.
xmpp.stop().catch(console.error)
xmpp.on('offline', () => {
console.log('offline')
})
Returns a promise that resolves once the stream closes and the socket disconnects.
send
Sends a stanza.
xmpp.send(xml('presence')).catch(console.error)
Returns a promise that resolves once the stanza is serialized and written to the socket or rejects if any of those fails.
xmpp.reconnect
Transports
XMPP supports multiple transports, this table list @xmpp-infister/client
supported and unsupported transport for each environment.
transport | protocols | Node.js | Browser | React Native |
---|---|---|---|---|
WebSocket | ws(s):// | ✔ | ✔ | ✔ |
TCP | xmpp:// | ✔ | ✗ | ✗ |
TLS | xmpps:// | ✔ | ✗ | ✗ |
Authentication
Multiple authentication mechanisms are supported.
PLAIN should only be used over secure WebSocket (wss://)
, direct TLS (xmpps:
) or a TCP (xmpp:
) connection upgraded to TLS via STARTTLS
SASL | Node.js | Browser | React Native |
---|---|---|---|
ANONYMOUS | ✔ | ✔ | ✔ |
PLAIN | ✔ | ✔ | ✔ |
SCRAM-SHA-1 | ✔ | ☐ | ✗ |
- ☐ : Optional
- ✗ : Unavailable
- ✔ : Included