@xmpp/client

    0.13.0 • Public • Published

    client

    An XMPP client is an entity that connects to an XMPP server.

    @xmpp/client package includes a minimal set of features to connect and authenticate securely and reliably.

    It supports Node.js, browsers and React Native. See below for differences.

    Install

    npm install @xmpp/client @xmpp/debug

    Setup

    const { client, xml, jid } = require("@xmpp/client");

    or

    <script
      src="https://unpkg.com/@xmpp/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/client");
    const debug = require("@xmpp/debug");
    
    const xmpp = client({
      service: "ws://localhost:5280/xmpp-websocket",
      domain: "localhost",
      resource: "example",
      username: "username",
      password: "password",
    });
    
    debug(xmpp, true);
    
    xmpp.on("error", (err) => {
      console.error(err);
    });
    
    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) => {
      // 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);
    });
    
    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/resolve
        • xmpp://hostname:port plain TCP, may be upgraded to TLS by @xmpp/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 from service. 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.

    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/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 { to, from } = stanza.attrs;
      stanza.attrs.from = to;
      stanza.attrs.to = from;
      xmpp.send(stanza);
    });

    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.

    sendMany

    Sends multiple stanzas.

    Here is an example sending the same text message to multiple recipients.

    const message = "Hello";
    const recipients = ["romeo@example.com", "juliet@example.com"];
    const stanzas = recipients.map((address) =>
      xml("message", { to: address, type: "chat" }, xml("body", null, message)),
    );
    xmpp.sendMany(stanzas).catch(console.error);

    Returns a promise that resolves once all the stanzas have been sent.

    If you need to send a stanza to multiple recipients we recommend using Extended Stanza Addressing instead.

    xmpp.reconnect

    See @xmpp/reconnect.

    Transports

    XMPP supports multiple transports, this table list @xmpp/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/client/reat-native instead of @xmpp/client.

    Keywords

    none

    Install

    npm i @xmpp/client

    DownloadsWeekly Downloads

    2,942

    Version

    0.13.0

    License

    ISC

    Unpacked Size

    530 kB

    Total Files

    14

    Last publish

    Collaborators

    • sonny