@sockethub/platform-irc 4.0.0-alpha.4 → 4.0.0-alpha.6

package/API.md

@@ -1,45 +1,56 @@
-<a name="IRC"></a>
-
-# IRC
-IRC
-
-**Kind**: global class  
-
-* [IRC](#IRC)
-    * [new IRC(cfg)](#new_IRC_new)
-    * [.schema](#IRC+schema)
-    * [.connect(job, credentials, done)](#IRC+connect)
-    * [.join(job, done)](#IRC+join)
-    * [.leave(job, done)](#IRC+leave)
-    * [.send(job, done)](#IRC+send)
-    * [.update(job, done)](#IRC+update)
-    * [.query(job, done)](#IRC+query)
-
-<a name="new_IRC_new"></a>
-
-## new IRC(cfg)
-Handles all actions related to communication via. the IRC protocol.
-
-Uses the `irc-factory` node module as a base tool for interacting with IRC.
-
-[https://github.com/ircanywhere/irc-factory](https://github.com/ircanywhere/irc-factory)
-
-<table>
-  <thead>
-    <tr>
-      <th>Param</th><th>Type</th><th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-<tr>
-    <td>cfg</td><td><code>object</code></td><td><p>a unique config object for this instance // TODO LINK</p>
-</td>
-    </tr>  </tbody>
-</table>
-
-<a name="IRC+schema"></a>
-
-## irC.schema
+# Members
+
+<dl>
+<dt><a href="#schema">schema</a></dt>
+<dd><p>JSON schema defining the types this platform accepts.</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>
+<ul>
+<li><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></li>
+</ul>
+<p>Valid AS object for setting IRC credentials:</p>
+</dd>
+</dl>
+
+# Functions
+
+<dl>
+<dt><a href="#connect">connect(job, credentials, done)</a></dt>
+<dd><p>Function: connect</p>
+<p>Connect to an IRC server.</p>
+</dd>
+<dt><a href="#join">join(job, done)</a></dt>
+<dd><p>Function: join</p>
+<p>Join a room or private conversation.</p>
+</dd>
+<dt><a href="#leave">leave(job, done)</a></dt>
+<dd><p>Function leave</p>
+<p>Leave a room or private conversation.</p>
+</dd>
+<dt><a href="#send">send(job, done)</a></dt>
+<dd><p>Function: send</p>
+<p>Send a message to a room or private conversation.</p>
+</dd>
+<dt><a href="#update">update(job, credentials, done)</a></dt>
+<dd><p>Function: update</p>
+<p>Indicate a change (i.e. room topic update, or nickname change).</p>
+</dd>
+<dt><a href="#query">query(job, done)</a></dt>
+<dd><p>Function: query</p>
+<p>Indicate an intent to query something (e.g. get a list of users in a room).</p>
+</dd>
+<dt><a href="#disconnect">disconnect(job, done)</a></dt>
+<dd><p>Disconnect IRC client</p>
+</dd>
+</dl>
+
+<a name="schema"></a>
+
+# schema
 JSON schema defining the types this platform accepts.
 
 
@@ -56,7 +67,7 @@ see [Sockethub Client](https://github.com/sockethub/sockethub/wiki/Sockethub-Cli
 
 Valid AS object for setting IRC credentials:
 
-**Kind**: instance property of [<code>IRC</code>](#IRC)  
+**Kind**: global variable  
 **Example**  
 ```js
 {
@@ -72,21 +83,21 @@ Valid AS object for setting IRC credentials:
      type: 'credentials',
      server: 'irc.host.net',
      nick: 'testuser',
-     password: 'asdasdasdasd',
+     password: 'secret',
      port: 6697,
      secure: true,
      sasl: true
    }
  }
 ```
-<a name="IRC+connect"></a>
+<a name="connect"></a>
 
-## irC.connect(job, credentials, done)
+# connect(job, credentials, done)
 Function: connect
 
-Conenct to an IRC server.
+Connect to an IRC server.
 
-**Kind**: instance method of [<code>IRC</code>](#IRC)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -106,14 +117,14 @@ Conenct to an IRC server.
     </tr>  </tbody>
 </table>
 
-<a name="IRC+join"></a>
+<a name="join"></a>
 
-## irC.join(job, done)
+# join(job, done)
 Function: join
 
 Join a room or private conversation.
 
-**Kind**: instance method of [<code>IRC</code>](#IRC)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -122,10 +133,10 @@ Join 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>
@@ -148,14 +159,14 @@ Join a room or private conversation.
   object: {}
 }
 ```
-<a name="IRC+leave"></a>
+<a name="leave"></a>
 
-## irC.leave(job, done)
+# leave(job, done)
 Function leave
 
 Leave a room or private conversation.
 
-**Kind**: instance method of [<code>IRC</code>](#IRC)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -164,10 +175,10 @@ Leave 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>
@@ -190,14 +201,14 @@ Leave a room or private conversation.
   object: {}
 }
 ```
-<a name="IRC+send"></a>
+<a name="send"></a>
 
-## irC.send(job, done)
+# send(job, done)
 Function: send
 
 Send a message to a room or private conversation.
 
-**Kind**: instance method of [<code>IRC</code>](#IRC)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -206,10 +217,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>
@@ -236,14 +247,14 @@ Send a message to a room or private conversation.
    }
  }
 ```
-<a name="IRC+update"></a>
+<a name="update"></a>
 
-## irC.update(job, done)
+# update(job, credentials, done)
 Function: update
 
-Indicate a change (ie. room topic update, or nickname change).
+Indicate a change (i.e. room topic update, or nickname change).
 
-**Kind**: instance method of [<code>IRC</code>](#IRC)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -252,10 +263,13 @@ Indicate a change (ie. room topic update, or nickname change).
   </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 to verify this user is the right one</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>
@@ -280,7 +294,7 @@ change topic
   },
   object: {
     type: 'topic',
-    content: 'New version of Socekthub released!'
+    content: 'New version of Sockethub released!'
   }
 }
 ```
@@ -289,7 +303,7 @@ change topic
 change nickname
  {
    context: 'irc'
-   type: 'udpate',
+   type: 'update',
    actor: {
      id: 'slvrbckt@irc.freenode.net',
      type: 'person',
@@ -301,18 +315,18 @@ change nickname
    target: {
      id: 'cooldude@irc.freenode.net',
      type: 'person',
-     name: cooldude
+     name: 'cooldude'
    }
  }
 ```
-<a name="IRC+query"></a>
+<a name="query"></a>
 
-## irC.query(job, done)
+# query(job, done)
 Function: query
 
 Indicate an intent to query something (e.g. get a list of users in a room).
 
-**Kind**: instance method of [<code>IRC</code>](#IRC)  
+**Kind**: global function  
 <table>
   <thead>
     <tr>
@@ -321,10 +335,10 @@ Indicate an intent to query something (e.g. 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>
@@ -373,3 +387,35 @@ Indicate an intent to query something (e.g. get a list of users in a room).
    }
  }
 ```
+<a name="disconnect"></a>
+
+# disconnect(job, done)
+Disconnect IRC 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: 'irc',
+   type: 'disconnect',
+   actor: {
+     id: 'slvrbckt@irc.freenode.net',
+     type: 'person'
+   }
+ }
+```

package/README.md

@@ -1,96 +1,91 @@
-# sockethub-platform-irc
+# @sockethub/platform-irc
 
-A sockethub platform module implementing IRC functionality.
+A Sockethub platform module implementing IRC (Internet Relay Chat) functionality.
 
 ## About
 
-This module contains all of the implementation details of an IRC client and is
-used as a sockethub platform.
+This platform provides IRC client functionality, allowing web applications to connect to
+IRC servers, join channels, send messages, and handle IRC events through ActivityStreams
+messages.
 
-## Implemented (`@type`)
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) send</kbd> 
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) join</kbd> 
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) leave</kbd> 
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) observe</kbd> 
-<kbd>![completed](http://sockethub.org/res/img/checkmark.png) update</kbd>
+## Implemented Verbs (`@type`)
 
-## Example
+* **send** - Send messages to channels or users
+* **join** - Join IRC channels
+* **leave** - Leave IRC channels
+* **observe** - Monitor channel activity and user events
+* **update** - Update user information (nick, etc.)
 
-Each sockethub platform uses JSON Activity Streams 2.0 which are received from and sent to clients, through the Sockethub service.
+## Usage
 
-### Incoming 
-Connected to IRC
+### Send Message Example
 
 ```json
 {
-  "@type": "announce",
+  "@type": "send",
   "context": "irc",
   "actor": {
-    "@id": "irc.freenode.net",
-    "@type": "service"
+    "@id": "mynick@irc.libera.chat"
   },
-  "published": "2015-05-20T22:32:06.212Z",
   "target": {
-    "@id": "foobar@irc.freenode.net",
-    "@type": "person",
-    "displayName": "Foobar McUser"
+    "@id": "#general@irc.libera.chat"
   },
   "object": {
-    "@type": "content",
-    "content": {
-      "network":{
-         "name":"freenode",
-         "hostname":"orwell.freenode.net",
-         "ircd":"ircd-seven-1.1.3",
-         "nicklength":16,
-         "maxtargets":{
-            "NAMES":1,
-            "LIST":1,
-            "KICK":1,
-            "WHOIS":1,
-            "PRIVMSG":4,
-            "NOTICE":4,
-            "ACCEPT":0,
-            "MONITOR":0
-         }
-      },
-      "channel":{
-         "idlength":{
-
-         },
-         "limit":{
-            "#":120
-         },
-         "length":50,
-         "modes":4,
-         "types":"#",
-         "kicklength":0,
-         "topiclength":390
-      },
-      "modes":{
-         "user":"DOQRSZaghilopswz",
-         "channel":"CFILMPQSbcefgijklmnopqrstvz",
-         "param":"bkloveqjfI",
-         "types":{
-            "a":"eIbq",
-            "b":"kov",
-            "c":"flj",
-            "d":"CFLMPQScgimnprstz"
-         },
-         "prefixes":"@+",
-         "prefixmodes":{
-            "o":"@",
-            "v":"+"
-         },
-         "maxlist":{
-            "bqeI":100
-         }
-      }
-    }
+    "@type": "Note",
+    "content": "Hello IRC channel!"
   }
 }
 ```
 
+### Join Channel Example
+
+```json
+{
+  "@type": "join",
+  "context": "irc",
+  "actor": {
+    "@id": "mynick@irc.libera.chat"
+  },
+  "target": {
+    "@id": "#general@irc.libera.chat"
+  }
+}
+```
+
+### Private Message Example
+
+```json
+{
+  "@type": "send",
+  "context": "irc",
+  "actor": {
+    "@id": "mynick@irc.libera.chat"
+  },
+  "target": {
+    "@id": "friend@irc.libera.chat"
+  },
+  "object": {
+    "@type": "Note",
+    "content": "Hello friend!"
+  }
+}
+```
+
+## Features
+
+* **Channel communication**: Join and participate in IRC channels
+* **Private messaging**: Send direct messages to other users
+* **User management**: Handle nick changes and user information
+* **Network support**: Connect to various IRC networks
+* **Event handling**: Process IRC events and convert to ActivityStreams
+
+## Use Cases
+
+* **Web IRC clients**: Build browser-based IRC chat applications
+* **Chatbots**: Create IRC bots that integrate with web services
+* **Notification systems**: Send alerts to IRC channels
+* **Community integration**: Connect web platforms to IRC communities
+
 ## 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-irc",
   "description": "A sockethub platform module implementing IRC functionality",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
   "private": false,
   "author": "Nick Jennings <nick@silverbucket.net>",
   "license": "LGPL-3.0+",
-  "main": "index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "engines": {
+    "bun": ">=1.2"
+  },
   "keywords": [
     "sockethub",
     "messaging",
@@ -22,20 +29,16 @@
   },
   "homepage": "https://github.com/sockethub/sockethub/tree/master/packages/platform-irc",
   "dependencies": {
-    "@sockethub/irc2as": "^4.0.0-alpha.4",
+    "@sockethub/irc2as": "4.0.0-alpha.6",
     "irc-socket-sasl": "4.0.0"
   },
   "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",
-    "proxyquire": "2.1.3",
-    "sinon": "14.0.0"
+    "@sockethub/schemas": "3.0.0-alpha.6",
+    "@types/bun": "latest",
+    "typedoc": "^0.28.14"
   },
   "peerDependencies": {
-    "@sockethub/server": ">=5.0.0-alpha.2"
+    "@sockethub/server": "5.0.0-alpha.6"
   },
   "peerDependenciesMeta": {
     "@sockethub/server": {
@@ -43,15 +46,7 @@
     }
   },
   "scripts": {
-    "build": "true",
-    "clean": "npx rimraf coverage",
-    "clean:deps": "npx rimraf coverage node_modules",
-    "compliance": "yarn run lint && yarn run test && yarn run coverage",
-    "test": "c8 mocha *.test.js",
-    "coverage": "c8 check-coverage --statements 80 --branches 55 --functions 85 --lines 80",
-    "doc": "jsdoc2md --no-gfm --heading-depth 1 index.js  > API.md",
-    "lint": "eslint \"**/*.js\"",
-    "lint:fix": "eslint --fix \"**/*.js\""
-  },
-  "gitHead": "c6d34ff44d2be479e4ea42c46da649612342a680"
+    "doc": "typedoc --options typedoc.json"
+  },
+  "gitHead": "f8a937e071e7a209f94b94f63e68faa27784e00e"
 }

package/src/index.test.data.ts

@@ -0,0 +1,60 @@
+export default [
+    {
+        name: "irc credentials",
+        valid: true,
+        type: "credentials",
+        input: {
+            context: "irc",
+            type: "credentials",
+            actor: {
+                id: "sh-9K3Vk@irc.freenode.net",
+                type: "person",
+                name: "sh-9K3Vk",
+                image: {
+                    height: 250,
+                    mediaType: "image/jpeg",
+                    url: "http://example.org/image.jpg",
+                    width: 250,
+                },
+                url: "http://sockethub.org",
+            },
+            object: {
+                type: "credentials",
+                nick: "sh-9K3Vk",
+                port: 6667,
+                secure: false,
+                server: "irc.freenode.net",
+            },
+        },
+        output: "same",
+    },
+    {
+        name: "bad irc credentials: user/nick host/server",
+        valid: false,
+        type: "credentials",
+        input: {
+            context: "irc",
+            type: "credentials",
+            actor: {
+                id: "sh-9K3Vk@irc.freenode.net",
+                type: "person",
+                name: "sh-9K3Vk",
+                image: {
+                    height: 250,
+                    mediaType: "image/jpeg",
+                    url: "http://example.org/image.jpg",
+                    width: 250,
+                },
+                url: "http://sockethub.org",
+            },
+            object: {
+                type: "credentials",
+                user: "sh-9K3Vk",
+                port: 6667,
+                secure: false,
+                host: "irc.freenode.net",
+            },
+        },
+        error: "Error: [irc] /object: must NOT have additional properties: host",
+    },
+];