@sockethub/platform-xmpp 5.0.0-alpha.4 → 5.0.0-alpha.6

package/API.md

@@ -1,50 +1,67 @@
-<a name="XMPP"></a>
+# Members
 
-# XMPP
-Handles all actions related to communication via. the XMPP protocol.
-
-Uses `xmpp.js` as a base tool for interacting with XMPP.
-
-[https://github.com/xmppjs/xmpp.js](https://github.com/xmppjs/xmpp.js)
-
-**Kind**: global class  
-
-* [XMPP](#XMPP)
-    * [new XMPP(session)](#new_XMPP_new)
-    * [.schema](#XMPP+schema)
-    * [.connect(job, credentials, done)](#XMPP+connect)
-    * [.join(job, done)](#XMPP+join)
-    * [.leave(job, done)](#XMPP+leave)
-    * [.send(job, done)](#XMPP+send)
-    * [.update(job, done)](#XMPP+update)
-    * [.request-friend(job, done)](#XMPP+request-friend)
-    * [.remove-friend(job, done)](#XMPP+remove-friend)
-    * [.make-friend(job, done)](#XMPP+make-friend)
-    * [.query(job, done)](#XMPP+query)
-    * [.cleanup(done)](#XMPP+cleanup)
-
-<a name="new_XMPP_new"></a>
-
-## new XMPP(session)
-Constructor called from the Sockethub `Platform` instance, passing in a
-session object.
-
-<table>
-  <thead>
-    <tr>
-      <th>Param</th><th>Type</th><th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-<tr>
-    <td>session</td><td><code>object</code></td><td><p><a href="Sockethub.Platform.PlatformSession#object">Sockethub.Platform.PlatformSession#object</a></p>
-</td>
-    </tr>  </tbody>
-</table>
-
-<a name="XMPP+schema"></a>
-
-## xmpP.schema
+<dl>
+<dt><a href="#schema">schema</a></dt>
+<dd><p>JSON schema defining the types this platform accepts.</p>
+<p>Actual handling of incoming &#39;set&#39; commands are handled by dispatcher,
+but the dispatcher uses this defined schema to validate credentials
+received, so that when a @context type is called, it can fetch the
+credentials (<code>session.getConfig()</code>), knowing they will have already been
+validated against this schema.</p>
+<p>In the below example, Sockethub will validate the incoming credentials object
+against whatever is defined in the <code>credentials</code> portion of the schema
+object.</p>
+<p>It will also check if the incoming AS object uses a type which exists in the
+<code>types</code> portion of the schema object (should be an array of type names).</p>
+<p><strong>NOTE</strong>: For more information on using the credentials object from a client,
+see <a href="https://github.com/sockethub/sockethub/wiki/Sockethub-Client">Sockethub Client</a></p>
+<p>Valid AS object for setting XMPP credentials:</p>
+</dd>
+</dl>
+
+# Functions
+
+<dl>
+<dt><a href="#connect">connect(job, credentials, done)</a></dt>
+<dd><p>Connect to the XMPP server.</p>
+</dd>
+<dt><a href="#join">join(job, done)</a></dt>
+<dd><p>Join a room, optionally defining a display name for that room.</p>
+</dd>
+<dt><a href="#leave">leave(job, done)</a></dt>
+<dd><p>Leave a room</p>
+</dd>
+<dt><a href="#send">send(job, done)</a></dt>
+<dd><p>Send a message to a room or private conversation.</p>
+</dd>
+<dt><a href="#update">update(job, done)</a></dt>
+<dd><p>Indicate presence and status message.
+Valid presence values are &quot;away&quot;, &quot;chat&quot;, &quot;dnd&quot;, &quot;xa&quot;, &quot;offline&quot;, &quot;online&quot;.</p>
+</dd>
+<dt><a href="#request-friend">request-friend(job, done)</a></dt>
+<dd><p>Send friend request</p>
+</dd>
+<dt><a href="#remove-friend">remove-friend(job, done)</a></dt>
+<dd><p>Send a remove friend request</p>
+</dd>
+<dt><a href="#make-friend">make-friend(job, done)</a></dt>
+<dd><p>Confirm a friend request</p>
+</dd>
+<dt><a href="#query">query(job, done)</a></dt>
+<dd><p>Indicate an intent to query something (i.e. get a list of users in a room).</p>
+</dd>
+<dt><a href="#disconnect">disconnect(job, done)</a></dt>
+<dd><p>Disconnect XMPP client</p>
+</dd>
+<dt><a href="#cleanup">cleanup(done)</a></dt>
+<dd><p>Called when it&#39;s time to close any connections or clean data before being wiped
+forcefully.</p>
+</dd>
+</dl>
+
+<a name="schema"></a>
+
+# schema
 JSON schema defining the types this platform accepts.
 
 Actual handling of incoming 'set' commands are handled by dispatcher,
@@ -67,7 +84,7 @@ see [Sockethub Client](https://github.com/sockethub/sockethub/wiki/Sockethub-Cli
 
 Valid AS object for setting XMPP credentials:
 
-**Kind**: instance property of [<code>XMPP</code>](#XMPP)  
+**Kind**: global variable  
 **Example**  
 ```js
 {
@@ -86,12 +103,12 @@ Valid AS object for setting XMPP credentials:
   }
 }
 ```
-<a name="XMPP+connect"></a>
+<a name="connect"></a>
 
-## xmpP.connect(job, credentials, done)
+# connect(job, credentials, done)
 Connect to the XMPP server.
 
-**Kind**: instance method of [<code>XMPP</code>](#XMPP)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -100,13 +117,13 @@ Connect to the XMPP server.
   </thead>
   <tbody>
 <tr>
-    <td>job</td><td><code>object</code></td><td><p>activity streams object // TODO LINK</p>
+    <td>job</td><td><code>object</code></td><td><p>activity streams object</p>
 </td>
     </tr><tr>
-    <td>credentials</td><td><code>object</code></td><td><p>credentials object // TODO LINK</p>
+    <td>credentials</td><td><code>object</code></td><td><p>credentials object</p>
 </td>
     </tr><tr>
-    <td>done</td><td><code>object</code></td><td><p>callback when job is done // TODO LINK</p>
+    <td>done</td><td><code>object</code></td><td><p>callback when job is done</p>
 </td>
     </tr>  </tbody>
 </table>
@@ -124,12 +141,12 @@ Connect to the XMPP server.
   }
 }
 ```
-<a name="XMPP+join"></a>
+<a name="join"></a>
 
-## xmpP.join(job, done)
+# join(job, done)
 Join a room, optionally defining a display name for that room.
 
-**Kind**: instance method of [<code>XMPP</code>](#XMPP)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -138,10 +155,10 @@ Join a room, optionally defining a display name for that room.
   </thead>
   <tbody>
 <tr>
-    <td>job</td><td><code>object</code></td><td><p>activity streams object // TODO LINK</p>
+    <td>job</td><td><code>object</code></td><td><p>activity streams object</p>
 </td>
     </tr><tr>
-    <td>done</td><td><code>object</code></td><td><p>callback when job is done // TODO LINK</p>
+    <td>done</td><td><code>object</code></td><td><p>callback when job is done</p>
 </td>
     </tr>  </tbody>
 </table>
@@ -162,12 +179,12 @@ Join a room, optionally defining a display name for that room.
   }
 }
 ```
-<a name="XMPP+leave"></a>
+<a name="leave"></a>
 
-## xmpP.leave(job, done)
+# leave(job, done)
 Leave a room
 
-**Kind**: instance method of [<code>XMPP</code>](#XMPP)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -176,10 +193,10 @@ Leave a room
   </thead>
   <tbody>
 <tr>
-    <td>job</td><td><code>object</code></td><td><p>activity streams object // TODO LINK</p>
+    <td>job</td><td><code>object</code></td><td><p>activity streams object</p>
 </td>
     </tr><tr>
-    <td>done</td><td><code>object</code></td><td><p>callback when job is done // TODO LINK</p>
+    <td>done</td><td><code>object</code></td><td><p>callback when job is done</p>
 </td>
     </tr>  </tbody>
 </table>
@@ -200,12 +217,12 @@ Leave a room
   }
 }
 ```
-<a name="XMPP+send"></a>
+<a name="send"></a>
 
-## xmpP.send(job, done)
+# send(job, done)
 Send a message to a room or private conversation.
 
-**Kind**: instance method of [<code>XMPP</code>](#XMPP)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -214,10 +231,10 @@ Send a message to a room or private conversation.
   </thead>
   <tbody>
 <tr>
-    <td>job</td><td><code>object</code></td><td><p>activity streams object // TODO LINK</p>
+    <td>job</td><td><code>object</code></td><td><p>activity streams object</p>
 </td>
     </tr><tr>
-    <td>done</td><td><code>object</code></td><td><p>callback when job is done // TODO LINK</p>
+    <td>done</td><td><code>object</code></td><td><p>callback when job is done</p>
 </td>
     </tr>  </tbody>
 </table>
@@ -263,13 +280,13 @@ Send a message to a room or private conversation.
   }
 }
 ```
-<a name="XMPP+update"></a>
+<a name="update"></a>
 
-## xmpP.update(job, done)
+# update(job, done)
 Indicate presence and status message.
 Valid presence values are "away", "chat", "dnd", "xa", "offline", "online".
 
-**Kind**: instance method of [<code>XMPP</code>](#XMPP)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -278,10 +295,10 @@ Valid presence values are "away", "chat", "dnd", "xa", "offline", "online".
   </thead>
   <tbody>
 <tr>
-    <td>job</td><td><code>object</code></td><td><p>activity streams object // TODO LINK</p>
+    <td>job</td><td><code>object</code></td><td><p>activity streams object</p>
 </td>
     </tr><tr>
-    <td>done</td><td><code>object</code></td><td><p>callback when job is done // TODO LINK</p>
+    <td>done</td><td><code>object</code></td><td><p>callback when job is done</p>
 </td>
     </tr>  </tbody>
 </table>
@@ -301,12 +318,12 @@ Valid presence values are "away", "chat", "dnd", "xa", "offline", "online".
   }
 }
 ```
-<a name="XMPP+request-friend"></a>
+<a name="request-friend"></a>
 
-## xmpP.request-friend(job, done)
+# request-friend(job, done)
 Send friend request
 
-**Kind**: instance method of [<code>XMPP</code>](#XMPP)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -315,10 +332,10 @@ Send friend request
   </thead>
   <tbody>
 <tr>
-    <td>job</td><td><code>object</code></td><td><p>activity streams object // TODO LINK</p>
+    <td>job</td><td><code>object</code></td><td><p>activity streams object</p>
 </td>
     </tr><tr>
-    <td>done</td><td><code>object</code></td><td><p>callback when job is done // TODO LINK</p>
+    <td>done</td><td><code>object</code></td><td><p>callback when job is done</p>
 </td>
     </tr>  </tbody>
 </table>
@@ -336,12 +353,12 @@ Send friend request
   }
 }
 ```
-<a name="XMPP+remove-friend"></a>
+<a name="remove-friend"></a>
 
-## xmpP.remove-friend(job, done)
+# remove-friend(job, done)
 Send a remove friend request
 
-**Kind**: instance method of [<code>XMPP</code>](#XMPP)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -350,10 +367,10 @@ Send a remove friend request
   </thead>
   <tbody>
 <tr>
-    <td>job</td><td><code>object</code></td><td><p>activity streams object // TODO LINK</p>
+    <td>job</td><td><code>object</code></td><td><p>activity streams object</p>
 </td>
     </tr><tr>
-    <td>done</td><td><code>object</code></td><td><p>callback when job is done // TODO LINK</p>
+    <td>done</td><td><code>object</code></td><td><p>callback when job is done</p>
 </td>
     </tr>  </tbody>
 </table>
@@ -371,12 +388,12 @@ Send a remove friend request
   }
 }
 ```
-<a name="XMPP+make-friend"></a>
+<a name="make-friend"></a>
 
-## xmpP.make-friend(job, done)
+# make-friend(job, done)
 Confirm a friend request
 
-**Kind**: instance method of [<code>XMPP</code>](#XMPP)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -385,10 +402,10 @@ Confirm a friend request
   </thead>
   <tbody>
 <tr>
-    <td>job</td><td><code>object</code></td><td><p>activity streams object // TODO LINK</p>
+    <td>job</td><td><code>object</code></td><td><p>activity streams object</p>
 </td>
     </tr><tr>
-    <td>done</td><td><code>object</code></td><td><p>callback when job is done // TODO LINK</p>
+    <td>done</td><td><code>object</code></td><td><p>callback when job is done</p>
 </td>
     </tr>  </tbody>
 </table>
@@ -406,12 +423,12 @@ Confirm a friend request
   }
 }
 ```
-<a name="XMPP+query"></a>
+<a name="query"></a>
 
-## xmpP.query(job, done)
-Indicate an intent to query something (ie. get a list of users in a room).
+# query(job, done)
+Indicate an intent to query something (i.e. get a list of users in a room).
 
-**Kind**: instance method of [<code>XMPP</code>](#XMPP)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -420,10 +437,10 @@ Indicate an intent to query something (ie. get a list of users in a room).
   </thead>
   <tbody>
 <tr>
-    <td>job</td><td><code>object</code></td><td><p>activity streams object // TODO LINK</p>
+    <td>job</td><td><code>object</code></td><td><p>activity streams object</p>
 </td>
     </tr><tr>
-    <td>done</td><td><code>object</code></td><td><p>callback when job is done // TODO LINK</p>
+    <td>done</td><td><code>object</code></td><td><p>callback when job is done</p>
 </td>
     </tr>  </tbody>
 </table>
@@ -470,13 +487,45 @@ Indicate an intent to query something (ie. get a list of users in a room).
    }
  }
 ```
-<a name="XMPP+cleanup"></a>
+<a name="disconnect"></a>
+
+# disconnect(job, done)
+Disconnect XMPP client
+
+**Kind**: global function  
+<table>
+  <thead>
+    <tr>
+      <th>Param</th><th>Type</th><th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+<tr>
+    <td>job</td><td><code>object</code></td><td><p>activity streams object</p>
+</td>
+    </tr><tr>
+    <td>done</td><td></td><td></td>
+    </tr>  </tbody>
+</table>
+
+**Example**  
+```js
+{
+   context: 'xmpp',
+   type: 'disconnect',
+   actor: {
+     id: 'slvrbckt@jabber.net/Home',
+     type: 'person'
+   }
+ }
+```
+<a name="cleanup"></a>
 
-## xmpP.cleanup(done)
+# cleanup(done)
 Called when it's time to close any connections or clean data before being wiped
 forcefully.
 
-**Kind**: instance method of [<code>XMPP</code>](#XMPP)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>

package/README.md

@@ -1,32 +1,89 @@
 # @sockethub/platform-xmpp
-A Sockethub platform module implementing XMPP functionality.
 
-## Overview
-Each Sockethub platform uses JSON Activity Streams 2.0 which are recevied from and sent to clients, through the Sockethub service.
+A Sockethub platform module implementing XMPP (Jabber) functionality for instant messaging and presence.
+
+## About
+
+This platform provides XMPP client functionality, allowing web applications to connect to
+XMPP servers, send messages, manage contacts, join chat rooms, and handle presence
+updates through ActivityStreams messages.
 
 ## Implemented Verbs (`@type`)
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) send</kbd> 
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) request-friend</kbd> 
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) remove-friend</kbd> 
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) make-friend</kbd> 
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) update</kbd> 
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png)  join</kbd> 
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) observe</kbd>
 
-## Example
+* **send** - Send messages to contacts or chat rooms
+* **join** - Join XMPP chat rooms (MUCs)
+* **observe** - Subscribe to presence updates
+* **request-friend** - Send contact/buddy requests
+* **remove-friend** - Remove contacts from roster
+* **make-friend** - Accept contact requests
+* **update** - Update presence status and information
+
+## Usage
 
+### Send Message Example
+
+```json
+{
+  "@type": "send",
+  "context": "xmpp",
+  "actor": {
+    "@id": "user@example.org"
+  },
+  "target": {
+    "@id": "friend@jabber.net"
+  },
+  "object": {
+    "@type": "Note",
+    "content": "Hello from Sockethub!"
+  }
+}
 ```
+
+### Join Chat Room Example
+
+```json
 {
-  context: 'xmpp',
-  '@type': 'request-friend',
-  actor: {
-    '@id': 'user@host.org/Home'
+  "@type": "join",
+  "context": "xmpp",
+  "actor": {
+    "@id": "user@example.org"
   },
-  target: {
-    '@id': 'homer@jabber.net/Home',
+  "target": {
+    "@id": "room@conference.example.org"
   }
 }
 ```
 
+### Request Friend Example
+
+```json
+{
+  "@type": "request-friend",
+  "context": "xmpp",
+  "actor": {
+    "@id": "user@example.org"
+  },
+  "target": {
+    "@id": "friend@jabber.net"
+  }
+}
+```
+
+## Features
+
+* **Instant messaging**: Send and receive one-on-one messages
+* **Multi-user chat**: Join and participate in chat rooms (MUCs)
+* **Contact management**: Add, remove, and manage contact lists
+* **Presence**: Handle online/offline status and presence updates
+* **Authentication**: Support for various XMPP authentication methods
+
+## Use Cases
+
+* **Web-based chat**: Build XMPP chat clients in web browsers
+* **Integration platforms**: Connect web services to XMPP networks
+* **Notification systems**: Send alerts through XMPP messages
+* **Federated communication**: Connect to the decentralized XMPP network
+
 ## API
-API docs can be found [here](API.md)
+
+Detailed API documentation can be found [here](API.md)

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "@sockethub/platform-xmpp",
   "description": "A sockethub platform module implementing XMPP functionality",
-  "version": "5.0.0-alpha.4",
+  "version": "5.0.0-alpha.6",
   "private": false,
+  "type": "module",
   "author": "Nick Jennings <nick@silverbucket.net>",
   "license": "LGPL-3.0+",
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "src/index.js",
+  "engines": {
+    "bun": ">=1.2"
+  },
   "keywords": [
     "sockethub",
     "messaging",
@@ -22,20 +29,16 @@
   },
   "homepage": "https://github.com/sockethub/sockethub/tree/master/packages/platform-xmpp",
   "dependencies": {
-    "@xmpp/client": "^0.13.0"
+    "@xmpp/client": "^0.13.1"
   },
   "devDependencies": {
-    "@sockethub/schemas": "^3.0.0-alpha.4",
-    "c8": "7.12.0",
-    "chai": "4.3.6",
-    "eslint": "8.23.1",
-    "jsdoc-to-markdown": "7.1.1",
-    "mocha": "10.0.0",
-    "proxyquire": "2.1.3",
-    "sinon": "14.0.0"
+    "@sockethub/schemas": "3.0.0-alpha.6",
+    "@xmpp/xml": "0.13.3",
+    "jsdoc-to-markdown": "8.0.0",
+    "sinon": "17.0.1"
   },
   "peerDependencies": {
-    "@sockethub/server": ">=5.0.0-alpha.2"
+    "@sockethub/server": "5.0.0-alpha.6"
   },
   "peerDependenciesMeta": {
     "@sockethub/server": {
@@ -43,15 +46,7 @@
     }
   },
   "scripts": {
-    "build": "yarn run doc",
-    "clean": "npx rimraf coverage",
-    "clean:deps": "npx rimraf node_modules",
-    "compliance": "yarn run test && yarn run coverage",
-    "test": "c8 mocha **/*.test.js",
-    "lint": "eslint \"**/*.js\"",
-    "lint:fix": "eslint --fix \"**/*.js\"",
-    "coverage": "c8 check-coverage --statements 85 --branches 80 --functions 70 --lines 85",
     "doc": "jsdoc2md --no-gfm --heading-depth 1 src/index.js > API.md"
   },
-  "gitHead": "c6d34ff44d2be479e4ea42c46da649612342a680"
+  "gitHead": "f8a937e071e7a209f94b94f63e68faa27784e00e"
 }