@sockethub/platform-irc 4.0.0-alpha.11 → 4.0.0-alpha.12

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sockethub/platform-irc",
   "description": "A sockethub platform module implementing IRC functionality",
-  "version": "4.0.0-alpha.11",
+  "version": "4.0.0-alpha.12",
   "private": false,
   "author": "Nick Jennings <nick@silverbucket.net>",
   "license": "LGPL-3.0+",
@@ -46,21 +46,21 @@
     "doc": "typedoc --options typedoc.json"
   },
   "dependencies": {
-    "@sockethub/irc2as": "^4.0.0-alpha.11",
+    "@sockethub/irc2as": "^4.0.0-alpha.12",
     "irc-socket-sasl": "^4.0.0"
   },
   "devDependencies": {
-    "@sockethub/schemas": "^3.0.0-alpha.11",
+    "@sockethub/schemas": "^3.0.0-alpha.12",
     "@types/bun": "latest",
     "typedoc": "^0.28.14"
   },
   "peerDependencies": {
-    "@sockethub/server": "^5.0.0-alpha.11"
+    "@sockethub/server": "^5.0.0-alpha.12"
   },
   "peerDependenciesMeta": {
     "@sockethub/server": {
       "optional": true
     }
   },
-  "gitHead": "c243fa9e76c688ce5ffcf524400b1dd27dcce615"
+  "gitHead": "f039dab3c3f67cbbf204476fc397532e973f82a8"
 }

package/src/ambient.d.ts

@@ -0,0 +1,35 @@
+declare module "irc-socket-sasl" {
+    export interface IrcSocketInstance {
+        end?: () => void;
+        raw: (message: string) => void;
+        once: (
+            event: string,
+            handler: (...args: Array<unknown>) => void,
+        ) => void;
+        on: (event: string, handler: (...args: Array<unknown>) => void) => void;
+        connect: () => Promise<unknown>;
+    }
+    const IrcSocket: new (...args: Array<unknown>) => IrcSocketInstance;
+    export default IrcSocket;
+}
+
+declare module "@sockethub/irc2as" {
+    interface IrcToActivityStreamsOptions {
+        server: string;
+        contexts?: Array<string>;
+        context?: string;
+    }
+
+    export class IrcToActivityStreams {
+        constructor(options: IrcToActivityStreamsOptions);
+        input(data: unknown): void;
+        events: {
+            on(event: string, handler: (...args: Array<unknown>) => void): void;
+        };
+    }
+}
+
+declare module "./octal-hack.js" {
+    const buildCommand: (input: string) => string;
+    export default buildCommand;
+}

package/src/index.test.data.ts

@@ -4,7 +4,11 @@ export default [
         valid: true,
         type: "credentials",
         input: {
-            context: "irc",
+            "@context": [
+                "https://www.w3.org/ns/activitystreams",
+                "https://sockethub.org/ns/context/v1.jsonld",
+                "https://sockethub.org/ns/context/platform/irc/v1.jsonld",
+            ],
             type: "credentials",
             actor: {
                 id: "sh-9K3Vk@irc.freenode.net",
@@ -33,7 +37,11 @@ export default [
         valid: false,
         type: "credentials",
         input: {
-            context: "irc",
+            "@context": [
+                "https://www.w3.org/ns/activitystreams",
+                "https://sockethub.org/ns/context/v1.jsonld",
+                "https://sockethub.org/ns/context/platform/irc/v1.jsonld",
+            ],
             type: "credentials",
             actor: {
                 id: "sh-9K3Vk@irc.freenode.net",

package/src/index.test.ts

@@ -3,7 +3,9 @@ import { beforeEach, describe, expect, it } from "bun:test";
 import {
     type ActivityStream,
     type CredentialsObject,
+    addPlatformContext,
     addPlatformSchema,
+    buildCanonicalContext,
     getPlatformSchema,
     validateCredentials,
     validatePlatformSchema,
@@ -30,8 +32,12 @@ const targetRoom = {
     name: "#a-room",
 };
 
+const IRC_CONTEXT = buildCanonicalContext(
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld",
+);
+
 const validCredentials = {
-    context: "irc",
+    "@context": IRC_CONTEXT,
     type: "credentials",
     actor: actor,
     object: {
@@ -69,6 +75,7 @@ describe("Initialize IRC Platform", () => {
         if (!getPlatformSchema("irc/credentials")) {
             addPlatformSchema(platform.schema.credentials, `irc/credentials`);
         }
+        addPlatformContext("irc", platform.schema.contextUrl);
     });
 
     it("lists required types enum", () => {
@@ -102,25 +109,30 @@ describe("Initialize IRC Platform", () => {
         });
 
         it("invalid credentials type", () => {
-            expect(
-                validateCredentials({
-                    context: "irc",
-                    type: "credentials",
-                    // @ts-expect-error test invalid params
-                    object: {
-                        host: "example.com",
-                        port: "6667",
-                    },
-                }),
-            ).toEqual("[irc] /object: must have required property 'type'");
+            const result = validateCredentials({
+                "@context": IRC_CONTEXT,
+                type: "credentials",
+                actor,
+                // @ts-expect-error test invalid params
+                object: {
+                    host: "example.com",
+                    port: "6667",
+                },
+            });
+            expect([
+                "[irc] /object: must have required property 'type'",
+                "[irc] /object/port: must be number",
+                "[irc] /object: must match exactly one schema in oneOf: credentials, feed, message, me, person, room, service, platform, website, attendance, presence, relationship, topic, address, heartbeat",
+            ]).toContain(result);
         });
 
         it("invalid credentials port", () => {
             expect(
                 // @ts-expect-error test invalid params
                 validateCredentials({
-                    context: "irc",
+                    "@context": IRC_CONTEXT,
                     type: "credentials",
+                    actor,
                     object: {
                         type: "credentials",
                         host: "example.com",
@@ -134,8 +146,9 @@ describe("Initialize IRC Platform", () => {
             expect(
                 // @ts-expect-error test invalid params
                 validateCredentials({
-                    context: "irc",
+                    "@context": IRC_CONTEXT,
                     type: "credentials",
+                    actor,
                     object: {
                         type: "credentials",
                         host: "example.com",
@@ -152,7 +165,7 @@ describe("Initialize IRC Platform", () => {
         beforeEach((done) => {
             platform.connect(
                 {
-                    context: "irc",
+                    "@context": IRC_CONTEXT,
                     type: "connect",
                     actor: actor,
                 },
@@ -165,7 +178,7 @@ describe("Initialize IRC Platform", () => {
             beforeEach((done) => {
                 platform.join(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "join",
                         actor: actor,
                         target: targetRoom,
@@ -182,7 +195,7 @@ describe("Initialize IRC Platform", () => {
             it("leave()", (done) => {
                 platform.leave(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "leave",
                         actor: actor,
                         target: targetRoom,
@@ -195,7 +208,7 @@ describe("Initialize IRC Platform", () => {
             it("send()", (done) => {
                 platform.send(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "send",
                         actor: actor,
                         object: { content: "har dee dar" },
@@ -209,7 +222,7 @@ describe("Initialize IRC Platform", () => {
             it("update() topic", (done) => {
                 platform.update(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "update",
                         actor: actor,
                         object: { type: "topic", content: "important details" },
@@ -224,7 +237,7 @@ describe("Initialize IRC Platform", () => {
             it("update() nick change", (done) => {
                 platform.update(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "update",
                         actor: actor,
                         object: { type: "address" },
@@ -239,7 +252,7 @@ describe("Initialize IRC Platform", () => {
             it("query()", (done) => {
                 platform.query(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "query",
                         actor: actor,
                         target: targetRoom,
@@ -258,7 +271,7 @@ describe("Initialize IRC Platform", () => {
                     cb();
                 }
                 platform.disconnect({
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "disconnect",
                         actor: actor,
                     },

package/src/index.ts

@@ -18,8 +18,6 @@
 
 import net from "node:net";
 import tls from "node:tls";
-import IrcSocket from "irc-socket-sasl";
-
 import { IrcToActivityStreams } from "@sockethub/irc2as";
 import type {
     ActivityStream,
@@ -32,15 +30,19 @@ import type {
     PlatformSession,
     PlatformUpdateActor,
 } from "@sockethub/schemas";
+import { buildCanonicalContext } from "@sockethub/schemas";
+import IrcSocket, { type IrcSocketInstance } from "irc-socket-sasl";
 
 import { PlatformIrcSchema } from "./schema.js";
 import type { PlatformIrcCredentialsObject } from "./types.js";
 
 export type GetClientCallback = (
     err: string | null,
-    client?: typeof IrcSocket,
+    client?: IrcSocketInstance,
 ) => void;
 
+type JobQueueHandler = (err?: Error | string) => void | Promise<void>;
+
 interface IrcSocketOptionsCapabilities {
     requires: string[];
 }
@@ -86,12 +88,12 @@ export default class IRC implements PersistentPlatformInterface {
     };
     private readonly updateActor: PlatformUpdateActor;
     private readonly sendToClient: PlatformSendToClient;
-    private irc2as: typeof IrcToActivityStreams;
+    private irc2as!: IrcToActivityStreams;
     private forceDisconnect = false;
     private clientConnecting = false;
     private initialized = false;
-    private client: typeof IrcSocket;
-    private jobQueue = []; // list of handlers to confirm when message delivery confirmed
+    private client?: IrcSocketInstance;
+    private jobQueue: Array<JobQueueHandler> = []; // list of handlers to confirm when message delivery confirmed
     private channels = new Set();
     private handledActors = new Set();
 
@@ -330,9 +332,11 @@ export default class IRC implements PersistentPlatformInterface {
                 // so the following line needs to be commented out when the API doc is built.
                 // investigate:
                 // https://github.com/jsdoc2md/jsdoc-to-markdown/issues/197#issuecomment-976851915
-                const buildCommand = await import("./octal-hack.js");
+                const { default: buildCommand } = await import(
+                    "./octal-hack.js"
+                );
                 const message = buildCommand(job.object.content);
-                // biome-ignore lint/style/useTemplate: <explanation>
+                // biome-ignore lint/style/useTemplate: IRC raw command formatting
                 client.raw("PRIVMSG " + job.target.name + " :" + message);
                 return done("IRC commands temporarily disabled");
             }
@@ -665,10 +669,7 @@ export default class IRC implements PersistentPlatformInterface {
             } sasl: ${is_sasl}`,
         );
 
-        const client: IrcSocket = new IrcSocket(
-            module_options,
-            is_secure ? tls : net,
-        );
+        const client = new IrcSocket(module_options, is_secure ? tls : net);
 
         const forceDisconnect = (err: string) => {
             this.forceDisconnect = true;
@@ -683,7 +684,7 @@ export default class IRC implements PersistentPlatformInterface {
         };
 
         client.once("error", (err: string) => {
-            this.log.debug(`irc client 'error' occurred. `, err);
+            this.log.debug(`irc client 'error' occurred.`, { err });
             forceDisconnect("error connecting to server.");
         });
 
@@ -710,7 +711,7 @@ export default class IRC implements PersistentPlatformInterface {
 
             this.log.debug(
                 `connected to ${module_options.server} capabilities: `,
-                capabilities,
+                { capabilities },
             );
             return cb(null, client);
         });
@@ -733,8 +734,11 @@ export default class IRC implements PersistentPlatformInterface {
     }
 
     private registerListeners(server: string) {
-        this.irc2as = new IrcToActivityStreams({ server: server });
-        this.client.on("data", (data: never) => {
+        this.irc2as = new IrcToActivityStreams({
+            server: server,
+            contexts: buildCanonicalContext(this.schema.contextUrl),
+        });
+        this.client.on("data", (data: unknown) => {
             this.irc2as.input(data);
         });
 

package/src/octal-hack.d.ts

@@ -0,0 +1,2 @@
+declare const buildCommand: (input: string) => string;
+export default buildCommand;

package/src/octal-hack.js

@@ -1,4 +1,4 @@
 module.exports = (content) => {
-    // biome-ignore lint/style/useTemplate: <explanation>
-    return "\001ACTION " + content + "\001";
+    // biome-ignore lint/style/useTemplate: IRC ACTION wrapper expects raw concatenation
+    return "\x01ACTION " + content + "\x01";
 };

package/src/schema.ts

@@ -1,9 +1,13 @@
 import packageJson from "../package.json" with { type: "json" };
+
 const version = packageJson.version;
 
 export const PlatformIrcSchema = {
     name: "irc",
     version: version,
+    contextUrl: "https://sockethub.org/ns/context/platform/irc/v1.jsonld",
+    contextVersion: "1",
+    schemaVersion: "1",
     messages: {
         required: ["type"],
         properties: {

package/src/types.ts

@@ -1,7 +1,7 @@
 import type { ActivityActor, CredentialsObject } from "@sockethub/schemas";
 
 export interface PlatformIrcCredentialsObject extends CredentialsObject {
-    context: "irc";
+    "@context": Array<string>;
     type: "credentials";
     actor: ActivityActor;
     target?: ActivityActor;