@sockethub/activity-streams 4.4.0-alpha.5 → 4.4.0-alpha.7

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "@sockethub/activity-streams",
-  "version": "4.4.0-alpha.5",
+  "version": "4.4.0-alpha.7",
   "description": "A simple tool to facilitate handling and referencing activity streams without unnecessary verbosity",
   "type": "module",
-  "main": "./src/activity-streams.ts",
+  "main": "./dist/activity-streams.js",
+  "exports": {
+    ".": {
+      "bun": "./src/activity-streams.ts",
+      "import": "./dist/activity-streams.js",
+      "default": "./dist/activity-streams.js"
+    }
+  },
   "files": [
+    "src/",
     "dist/"
   ],
   "engines": {
@@ -23,6 +31,9 @@
   ],
   "author": "Nick Jennings <nick@silverbucket.net>",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "bugs": {
     "url": "https://github.com/sockethub/sockethub/issues"
   },
@@ -35,13 +46,13 @@
     "test:browser": "wtr dist/**/*.test.js --node-resolve --puppeteer"
   },
   "dependencies": {
-    "eventemitter3": "5.0.1"
+    "eventemitter3": "^5.0.4"
   },
   "devDependencies": {
-    "@sockethub/schemas": "3.0.0-alpha.5",
+    "@sockethub/schemas": "^3.0.0-alpha.7",
     "@types/bun": "latest",
     "@web/test-runner": "^0.19.0",
     "@web/test-runner-puppeteer": "^0.17.0"
   },
-  "gitHead": "341ea9eeca6afd1442fe6e01457bc21d112b91a4"
+  "gitHead": "38927776c210a22bc54ceb86ccc7276c5f27b463"
 }

package/src/activity-streams.test.ts

@@ -0,0 +1,302 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import type { ActivityStream } from "@sockethub/schemas";
+import { ASFactory } from "./activity-streams";
+
+describe("warn test", () => {
+    expect(typeof ASFactory).toEqual("function");
+    const activity = ASFactory();
+    test("rejects nondefined special types", () => {
+        expect(() => {
+            activity.Stream({
+                type: "lol",
+                platform: "irc",
+                actor: "thingy",
+                object: { type: "hola", content: "har", secure: true },
+                target: ["thingy1", "thingy2"],
+            });
+        }).toThrow(Error);
+    });
+});
+
+describe("no special props", () => {
+    const activity = ASFactory();
+    test("init", () => {
+        expect(typeof ASFactory).toEqual("function");
+    });
+
+    test("returns expected object with no special types", () => {
+        expect(
+            activity.Stream({
+                type: "send",
+                context: "irc",
+                actor: "thingy",
+                object: { type: "hola", content: "har" },
+                target: ["thingy1", "thingy2"],
+            }),
+        ).toEqual({
+            type: "send",
+            context: "irc",
+            actor: { id: "thingy" },
+            object: { type: "hola", content: "har" },
+            target: ["thingy1", "thingy2"],
+        });
+    });
+});
+
+describe("basic tests", () => {
+    const config = {
+        customProps: {
+            credentials: ["secure"],
+            dude: ["foo", "secure"],
+        },
+        specialObjs: ["dude"],
+        failOnUnknownObjectProperties: true,
+    };
+
+    const activity = ASFactory(config);
+    test("init", () => {
+        expect(typeof ASFactory).toEqual("function");
+    });
+
+    describe("object tests", () => {
+        test("has expected structure", () => {
+            expect(typeof activity).toEqual("object");
+            expect(typeof activity.Object).toEqual("object");
+            expect(typeof activity.Stream).toEqual("function");
+            expect(typeof activity.on).toEqual("function");
+            expect(typeof activity.once).toEqual("function");
+            expect(typeof activity.off).toEqual("function");
+        });
+
+        test("returns undefined when no params are passed", () => {
+            // @ts-ignore
+            expect(activity.Object.get()).toBeUndefined();
+        });
+
+        test("returns object when given a valid lookup id", () => {
+            expect(activity.Object.create({ id: "thingy1" })).toEqual({
+                id: "thingy1",
+            });
+            expect(activity.Object.get("thingy1")).toEqual({
+                id: "thingy1",
+            });
+        });
+
+        test("throws an exception when called with no identifier", () => {
+            expect(activity.Object.create).toThrow(Error);
+        });
+
+        test("creates a second object and returns is as expected", () => {
+            expect(activity.Object.create({ id: "thingy2" })).toEqual({
+                id: "thingy2",
+            });
+            expect(activity.Object.get("thingy2")).toEqual({
+                id: "thingy2",
+            });
+        });
+
+        test("returns a basic ActivtyObject when receiving an unknown id with expand=true", () => {
+            expect(activity.Object.get("thingy3", true)).toEqual({
+                id: "thingy3",
+            });
+        });
+
+        test("returns given id param when lookup fails and expand=false", () => {
+            expect(
+                // @ts-ignore
+                activity.Object.get({
+                    id: "thingy3",
+                    foo: "bar",
+                }),
+            ).toEqual({
+                id: "thingy3",
+                foo: "bar",
+            });
+        });
+    });
+
+    interface TestActivityStream extends ActivityStream {
+        type: string;
+        verb?: string;
+        context: string;
+        platform?: string;
+    }
+
+    describe("stream tests", () => {
+        let stream: TestActivityStream;
+
+        beforeEach(() => {
+            stream = activity.Stream({
+                verb: "lol",
+                platform: "irc",
+                actor: "thingy1",
+                context: "irc",
+                object: {
+                    objectType: "credentials",
+                    content: "har",
+                    secure: true,
+                },
+                target: ["thingy1", "thingy2"],
+            }) as ActivityStream;
+        });
+
+        test("renames mapped props", () => {
+            expect(stream.type).toEqual("lol");
+            expect(stream.verb).toBeUndefined();
+            expect(stream.context).toEqual("irc");
+            expect(stream.platform).toBeUndefined();
+        });
+
+        test("expands existing objects", () => {
+            // @ts-ignore
+            expect(stream.target).toEqual([
+                { id: "thingy1" },
+                { id: "thingy2" },
+            ]);
+            // @ts-ignore
+            expect(stream.actor).toEqual({ id: "thingy1" });
+        });
+
+        test("handles customProps as expected", () => {
+            expect(stream.object).toEqual({
+                type: "credentials",
+                content: "har",
+                secure: true,
+            });
+            expect(stream.object.objectType).toBeUndefined();
+        });
+
+        test("respects specialObj properties", () => {
+            const stream2 = activity.Stream({
+                type: "lol",
+                platform: "irc",
+                actor: "thingy",
+                object: {
+                    type: "dude",
+                    foo: "bar",
+                    content: "har",
+                    secure: true,
+                },
+                target: ["thingy1", "thingy2"],
+            });
+            expect(stream2).toEqual({
+                type: "lol",
+                context: "irc",
+                actor: { id: "thingy" },
+                target: [{ id: "thingy1" }, { id: "thingy2" }],
+                object: {
+                    type: "dude",
+                    foo: "bar",
+                    content: "har",
+                    secure: true,
+                },
+            });
+        });
+
+        test("rejects nondefined special types", () => {
+            expect(() => {
+                activity.Stream({
+                    type: "lol",
+                    platform: "irc",
+                    actor: "thingy",
+                    object: {
+                        type: "hola",
+                        foo: "bar",
+                        content: "har",
+                        secure: true,
+                    },
+                    target: ["thingy1", "thingy2"],
+                });
+            }).toThrow('ActivityStreams validation failed: property "foo" with value "bar" is not allowed on the "object" object of type "hola".');
+        });
+    });
+
+    describe("emitters", () => {
+        test("emits an event on object creation", () => {
+            function onHandler(obj) {
+                expect(obj).toEqual({ id: "thingy3" });
+                activity.off("activity-object-create", onHandler);
+            }
+            activity.on("activity-object-create", onHandler);
+            activity.Object.create({ id: "thingy3" });
+        });
+
+        test("emits an event on object deletion", () => {
+            activity.once("activity-object-delete", (id) => {
+                expect(id).toEqual("thingy2");
+            });
+            activity.Object.delete("thingy2");
+        });
+    });
+});
+
+describe("Object.create error handling tests", () => {
+    const activity = ASFactory();
+
+    test("throws clear error when passed null", () => {
+        expect(() => {
+            // @ts-ignore - intentionally testing invalid input
+            activity.Object.create(null);
+        }).toThrow('ActivityStreams validation failed: the "object" property is null. Example: { id: "user@example.com", type: "person" }');
+    });
+
+    test("throws clear error when passed undefined", () => {
+        expect(() => {
+            // @ts-ignore - intentionally testing invalid input
+            activity.Object.create(undefined);
+        }).toThrow('ActivityStreams validation failed: the "object" property is undefined. Example: { id: "user@example.com", type: "person" }');
+    });
+
+    test("throws clear error when passed string", () => {
+        expect(() => {
+            // @ts-ignore - intentionally testing invalid input
+            activity.Object.create("string value");
+        }).toThrow('ActivityStreams validation failed: the "object" property received string "string value" but expected an object. Use: { id: "string value", type: "person" }');
+    });
+
+    test("throws clear error when passed number", () => {
+        expect(() => {
+            // @ts-ignore - intentionally testing invalid input
+            activity.Object.create(123);
+        }).toThrow('ActivityStreams validation failed: the "object" property must be an object, received number (123). Example: { id: "user@example.com", type: "person" }');
+    });
+
+    test("throws clear error when passed boolean false", () => {
+        expect(() => {
+            // @ts-ignore - intentionally testing invalid input
+            activity.Object.create(false);
+        }).toThrow('ActivityStreams validation failed: the "object" property must be an object, received boolean (false). Example: { id: "user@example.com", type: "person" }');
+    });
+
+    test("throws clear error when passed boolean true", () => {
+        expect(() => {
+            // @ts-ignore - intentionally testing invalid input
+            activity.Object.create(true);
+        }).toThrow('ActivityStreams validation failed: the "object" property must be an object, received boolean (true). Example: { id: "user@example.com", type: "person" }');
+    });
+
+    test("throws clear error when passed array", () => {
+        expect(() => {
+            // @ts-ignore - intentionally testing invalid input
+            activity.Object.create([]);
+        }).toThrow('ActivityStreams validation failed: the "object" property must be an object, received array (). Example: { id: "user@example.com", type: "person" }');
+    });
+
+    test("throws clear error when passed empty object (missing required id)", () => {
+        expect(() => {
+            activity.Object.create({});
+        }).toThrow('ActivityStreams validation failed: the "object" property requires an \'id\' property. Example: { id: "user@example.com", type: "person" }');
+    });
+
+    test("throws clear error when object has properties but missing id", () => {
+        expect(() => {
+            activity.Object.create({ type: "person", name: "John" });
+        }).toThrow('ActivityStreams validation failed: the "object" property requires an \'id\' property. Example: { id: "user@example.com", type: "person" }');
+    });
+
+    test("handles object with only id property", () => {
+        expect(() => {
+            activity.Object.create({ id: "test-id" });
+        }).not.toThrow();
+    });
+});

package/src/activity-streams.ts

@@ -0,0 +1,344 @@
+/*!
+ * activity-streams
+ *   https://github.com/silverbucket/activity-streams
+ *
+ * Developed and Maintained by:
+ *   Nick Jennings <nick@silverbucket.net>
+ *
+ * activity-streams is released under the MIT (see LICENSE).
+ *
+ * You don't have to do anything special to choose one license or the other
+ * and you don't have to notify anyone which license you are using.
+ * Please see the corresponding license file for details of these licenses.
+ * You are free to use, modify and distribute this software, but all copyright
+ * information must remain.
+ *
+ */
+
+import type { ActivityObject, ActivityStream } from "@sockethub/schemas";
+import EventEmitter from "eventemitter3";
+
+const ee = new EventEmitter();
+const baseProps = {
+    stream: [
+        "id",
+        "type",
+        "actor",
+        "target",
+        "object",
+        "context",
+        "context",
+        "published",
+        "error",
+    ],
+    object: [
+        "id",
+        "type",
+        "context",
+        "alias",
+        "attachedTo",
+        "attachment",
+        "attributedTo",
+        "attributedWith",
+        "condition",
+        "content",
+        "contentMap",
+        "context",
+        "contextOf",
+        "name",
+        "endTime",
+        "generator",
+        "generatorOf",
+        "group",
+        "icon",
+        "image",
+        "inReplyTo",
+        "members",
+        "memberOf",
+        "message",
+        "location",
+        "locationOf",
+        "objectOf",
+        "originOf",
+        "presence",
+        "preview",
+        "previewOf",
+        "provider",
+        "providerOf",
+        "published",
+        "rating",
+        "relationship",
+        "resultOf",
+        "replies",
+        "role",
+        "scope",
+        "scopeOf",
+        "startTime",
+        "status",
+        "summary",
+        "topic",
+        "tag",
+        "tagOf",
+        "targetOf",
+        "title",
+        "titleMap",
+        "updated",
+        "url",
+        "xmpp:stanza-id",
+    ],
+};
+const rename = {
+    "@id": "id",
+    "@type": "type",
+    verb: "type",
+    displayName: "name",
+    objectType: "type",
+    platform: "context",
+};
+const expand = {
+    actor: {
+        primary: "id",
+        props: baseProps,
+    },
+    target: {
+        primary: "id",
+        props: baseProps,
+    },
+    object: {
+        primary: "content",
+        props: baseProps,
+    },
+};
+
+type CustomProps = {
+    [key: string]: string | number | boolean | object | string[];
+};
+
+const objs = new Map();
+const customProps: CustomProps = {};
+
+let failOnUnknownObjectProperties = false;
+let warnOnUnknownObjectProperties = true;
+let specialObjs = []; // the objects don't get rejected for bad props
+
+function matchesCustomProp(type: string, key: string) {
+    if (customProps[type] instanceof Object) {
+        const obj = customProps[type] as string[];
+        if (obj.includes(key)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function renameProp<T>(obj: T, key: string): T {
+    obj[rename[key]] = obj[key];
+    delete obj[key];
+    return obj;
+}
+
+function validateObject<T>(type: string, incomingObj: T, requireId = false) {
+    // Input validation with clear error messages
+    if (incomingObj === null) {
+        throw new Error(
+            `ActivityStreams validation failed: the "${type}" property is null. Example: { id: "user@example.com", type: "person" }`,
+        );
+    }
+
+    if (incomingObj === undefined) {
+        throw new Error(
+            `ActivityStreams validation failed: the "${type}" property is undefined. Example: { id: "user@example.com", type: "person" }`,
+        );
+    }
+
+    if (typeof incomingObj === "string") {
+        throw new Error(
+            `ActivityStreams validation failed: the "${type}" property received string "${incomingObj}" but expected an object. Use: { id: "${incomingObj}", type: "person" }`,
+        );
+    }
+
+    if (typeof incomingObj !== "object" || Array.isArray(incomingObj)) {
+        const receivedType = Array.isArray(incomingObj)
+            ? "array"
+            : typeof incomingObj;
+        const receivedValue = String(incomingObj);
+        throw new Error(
+            `ActivityStreams validation failed: the "${type}" property must be an object, received ${receivedType} (${receivedValue}). Example: { id: "user@example.com", type: "person" }`,
+        );
+    }
+
+    // Require 'id' property when explicitly requested (e.g., Object.create())
+    const obj = incomingObj as ActivityObject;
+    if (requireId && !obj.id) {
+        throw new Error(
+            `ActivityStreams validation failed: the "${type}" property requires an 'id' property. Example: { id: "user@example.com", type: "person" }`,
+        );
+    }
+
+    const unknownKeys = Object.keys(incomingObj).filter(
+        (key: string): boolean => {
+            return !baseProps[type].includes(key);
+        },
+    );
+
+    for (const key of unknownKeys) {
+        let ao: ActivityObject = incomingObj as ActivityObject;
+        if (rename[key]) {
+            // rename property instead of fail
+            ao = renameProp(ao, key);
+            continue;
+        }
+
+        if (matchesCustomProp(ao.type, key)) {
+            // custom property matches, continue
+            continue;
+        }
+
+        if (!specialObjs.includes(ao.type)) {
+            // not defined as a special prop
+            // don't know what to do with it, so throw error
+            console.log(ao);
+            const receivedValue =
+                typeof ao[key] === "string" ? `"${ao[key]}"` : String(ao[key]);
+            const err = `ActivityStreams validation failed: property "${key}" with value ${receivedValue} is not allowed on the "${type}" object of type "${ao.type}".`;
+            if (failOnUnknownObjectProperties) {
+                throw new Error(err);
+            }
+            if (warnOnUnknownObjectProperties) {
+                console.warn(err);
+            }
+        }
+    }
+}
+
+function ensureProps(obj: ActivityObject): ActivityObject {
+    // ensure the name property, which can generally be inferred from the id
+    // name = obj.match(/(?(?\w+):\/\/)(?:.+@)?(.+?)(?:\/|$)/)[1]
+    return obj;
+}
+
+function expandStream(meta: ActivityStream) {
+    const stream = {};
+    for (const key of Object.keys(meta)) {
+        if (typeof meta[key] === "string") {
+            stream[key] = objs.get(meta[key]) || meta[key];
+        } else if (Array.isArray(meta[key])) {
+            stream[key] = [];
+            for (const entry of meta[key]) {
+                if (typeof entry === "string") {
+                    stream[key].push(objs.get(entry) || entry);
+                }
+            }
+        } else {
+            stream[key] = meta[key];
+        }
+    }
+
+    // only expand string into objects if they are in the expand list
+    for (const key of Object.keys(expand)) {
+        if (typeof stream[key] === "string") {
+            const idx = expand[key].primary;
+            const obj = {};
+            obj[idx] = stream[key];
+            stream[key] = obj;
+        }
+    }
+    return stream;
+}
+
+function Stream(
+    meta: ActivityStream,
+): ActivityStream | ActivityObject | Record<string, never> {
+    validateObject("stream", meta);
+    if (typeof meta.object === "object") {
+        validateObject("object", meta.object);
+    }
+    const stream = expandStream(meta);
+    ee.emit("activity-stream", stream);
+    return stream;
+}
+
+export interface ActivityObjectManager {
+    create(obj: unknown): unknown;
+    delete(id: string): boolean;
+    list(): IterableIterator<unknown>;
+    get(id: string, expand?: boolean): unknown;
+}
+
+const _Object: ActivityObjectManager = {
+    create: (obj: ActivityObject) => {
+        validateObject("object", obj, true); // require ID for Object.create()
+        const ao = ensureProps(obj);
+        objs.set(ao.id, ao);
+        ee.emit("activity-object-create", ao);
+        return ao;
+    },
+
+    delete: (id) => {
+        const result = objs.delete(id);
+        if (result) {
+            ee.emit("activity-object-delete", id);
+        }
+        return result;
+    },
+
+    get: (id, expand) => {
+        let obj = objs.get(id);
+        if (!obj) {
+            if (!expand) {
+                return id;
+            }
+            obj = { id: id };
+        }
+        return ensureProps(obj);
+    },
+
+    list: (): IterableIterator<unknown> => objs.keys(),
+};
+
+export interface ASFactoryOptions {
+    specialObjs?: Array<string>;
+    failOnUnknownObjectProperties?: boolean;
+    warnOnUnknownObjectProperties?: boolean;
+    customProps?: CustomProps;
+}
+
+type EventCallback = (...args: unknown[]) => void;
+
+export interface ASManager {
+    Stream(meta: unknown): ActivityStream | ActivityObject;
+    Object: ActivityObjectManager;
+    on(event: string, func: EventCallback): void;
+    once(event: string, func: EventCallback): void;
+    off(event: string, func: EventCallback): void;
+}
+
+export function ASFactory(opts: ASFactoryOptions = {}): ASManager {
+    specialObjs = opts?.specialObjs || [];
+    failOnUnknownObjectProperties =
+        typeof opts.failOnUnknownObjectProperties === "boolean"
+            ? opts.failOnUnknownObjectProperties
+            : failOnUnknownObjectProperties;
+    warnOnUnknownObjectProperties =
+        typeof opts.warnOnUnknownObjectProperties === "boolean"
+            ? opts.warnOnUnknownObjectProperties
+            : warnOnUnknownObjectProperties;
+    for (const propName of Object.keys(opts.customProps || {})) {
+        if (typeof opts.customProps[propName] === "object") {
+            customProps[propName] = opts.customProps[propName];
+        }
+    }
+
+    return {
+        Stream: Stream,
+        Object: _Object,
+        on: (event, func) => ee.on(event, func),
+        once: (event, func) => ee.once(event, func),
+        off: (event, funcName) => ee.off(event, funcName),
+    } as ASManager;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+((global: any) => {
+    global.ASFactor = ASFactory;
+})(typeof window === "object" ? window : {});