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/resolve -
xmpp://hostname:port
plain TCP, may be upgraded to TLS by @xmpp-infister/starttls -
xmpps://hostname:port
direct TLS -
ws://hostname:port/path
plain WebSocket -
wss://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 binding -
username
<string>
Optional username for sasl -
password
<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 connecting -
connect
: Socket is connected -
opening
: Stream is opening -
open
: Stream is open -
closing
: Stream is closing -
close
: Stream is closed -
disconnecting
: Socket is disconnecting -
disconnect
: 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.
status
Event Emitted when the status changes.
xmpp.on('status', status => {
console.debug(status)
})
error
Event 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)
})
stanza
Event 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)
})
online
Event Emitted when connected, authenticated and ready to receive/send stanzas.
xmpp.on('online', address => {
console.log('online as', address.toString())
})
offline
Event 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
Common issues
Unable to resolve module
If you are using an older React Native version, please require/import @xmpp-infister/client/reat-native
instead of @xmpp-infister/client
.