@sockethub/schemas 3.0.0-alpha.10 → 3.0.0-alpha.12

package/dist/maps/context-map.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": "3.0.0-alpha.12",
+  "generatedAt": "2026-03-29T20:04:59.384Z",
+  "contextToPlatformId": {
+    "https://sockethub.org/ns/context/platform/dummy/v1.jsonld": "dummy",
+    "https://sockethub.org/ns/context/platform/error/v1.jsonld": "error",
+    "https://sockethub.org/ns/context/platform/feeds/v1.jsonld": "feeds",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld": "irc",
+    "https://sockethub.org/ns/context/platform/metadata/v1.jsonld": "metadata",
+    "https://sockethub.org/ns/context/platform/sockethub:internal/v1.jsonld": "sockethub:internal",
+    "https://sockethub.org/ns/context/platform/xmpp/v1.jsonld": "xmpp"
+  },
+  "contextToSchemaId": {
+    "https://sockethub.org/ns/context/platform/dummy/v1.jsonld": "https://sockethub.org/schemas/as2/platform/dummy/v1/messages.schema.json",
+    "https://sockethub.org/ns/context/platform/error/v1.jsonld": "https://sockethub.org/schemas/as2/platform/error/v1/messages.schema.json",
+    "https://sockethub.org/ns/context/platform/feeds/v1.jsonld": "https://sockethub.org/schemas/as2/platform/feeds/v1/messages.schema.json",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld": "https://sockethub.org/schemas/as2/platform/irc/v1/messages.schema.json",
+    "https://sockethub.org/ns/context/platform/metadata/v1.jsonld": "https://sockethub.org/schemas/as2/platform/metadata/v1/messages.schema.json",
+    "https://sockethub.org/ns/context/platform/sockethub:internal/v1.jsonld": "https://sockethub.org/schemas/as2/platform/sockethub%3Ainternal/v1/messages.schema.json",
+    "https://sockethub.org/ns/context/platform/xmpp/v1.jsonld": "https://sockethub.org/schemas/as2/platform/xmpp/v1/messages.schema.json"
+  },
+  "contextToCredentialsSchemaId": {
+    "https://sockethub.org/ns/context/platform/dummy/v1.jsonld": "https://sockethub.org/schemas/as2/platform/dummy/v1/credentials.schema.json",
+    "https://sockethub.org/ns/context/platform/error/v1.jsonld": "https://sockethub.org/schemas/as2/platform/error/v1/credentials.schema.json",
+    "https://sockethub.org/ns/context/platform/feeds/v1.jsonld": "https://sockethub.org/schemas/as2/platform/feeds/v1/credentials.schema.json",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld": "https://sockethub.org/schemas/as2/platform/irc/v1/credentials.schema.json",
+    "https://sockethub.org/ns/context/platform/metadata/v1.jsonld": "https://sockethub.org/schemas/as2/platform/metadata/v1/credentials.schema.json",
+    "https://sockethub.org/ns/context/platform/sockethub:internal/v1.jsonld": "https://sockethub.org/schemas/as2/platform/sockethub%3Ainternal/v1/credentials.schema.json",
+    "https://sockethub.org/ns/context/platform/xmpp/v1.jsonld": "https://sockethub.org/schemas/as2/platform/xmpp/v1/credentials.schema.json"
+  },
+  "constants": {
+    "as2": "https://www.w3.org/ns/activitystreams",
+    "sockethub": "https://sockethub.org/ns/context/v1.jsonld"
+  }
+}

package/dist/schemas/platform/dummy/v1/credentials.schema.json

@@ -0,0 +1 @@
+{}

package/dist/schemas/platform/dummy/v1/messages.schema.json

@@ -0,0 +1,22 @@
+{
+  "required": [
+    "type"
+  ],
+  "properties": {
+    "type": {
+      "enum": [
+        "echo",
+        "fail",
+        "throw",
+        "greet",
+        "exit0",
+        "exit1",
+        "throwTypeError",
+        "throwReferenceError",
+        "sigterm",
+        "sigkill",
+        "hang"
+      ]
+    }
+  }
+}

package/dist/schemas/platform/error/v1/credentials.schema.json

@@ -0,0 +1 @@
+{}

package/dist/schemas/platform/error/v1/messages.schema.json

@@ -0,0 +1 @@
+{}

package/dist/schemas/platform/feeds/v1/credentials.schema.json

@@ -0,0 +1 @@
+{}

package/dist/schemas/platform/feeds/v1/messages.schema.json

@@ -0,0 +1,36 @@
+{
+  "required": [
+    "type"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "fetch"
+      ]
+    },
+    "object": {
+      "type": "object",
+      "oneOf": [
+        {
+          "$ref": "#/definitions/objectTypes/feed-parameters-date"
+        },
+        {
+          "$ref": "#/definitions/objectTypes/feed-parameters-url"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "objectTypes": {
+      "feed-parameters-date": {
+        "type": "object",
+        "additionalProperties": true
+      },
+      "feed-parameters-url": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    }
+  }
+}

package/dist/schemas/platform/irc/v1/credentials.schema.json

@@ -0,0 +1,48 @@
+{
+  "required": [
+    "object"
+  ],
+  "properties": {
+    "actor": {
+      "type": "object",
+      "required": [
+        "id"
+      ]
+    },
+    "object": {
+      "type": "object",
+      "required": [
+        "type",
+        "nick",
+        "server"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "nick": {
+          "type": "string"
+        },
+        "username": {
+          "type": "string"
+        },
+        "password": {
+          "type": "string"
+        },
+        "server": {
+          "type": "string"
+        },
+        "port": {
+          "type": "number"
+        },
+        "secure": {
+          "type": "boolean"
+        },
+        "sasl": {
+          "type": "boolean"
+        }
+      }
+    }
+  }
+}

package/dist/schemas/platform/irc/v1/messages.schema.json

@@ -0,0 +1,19 @@
+{
+  "required": [
+    "type"
+  ],
+  "properties": {
+    "type": {
+      "enum": [
+        "connect",
+        "update",
+        "join",
+        "leave",
+        "send",
+        "query",
+        "announce",
+        "disconnect"
+      ]
+    }
+  }
+}

package/dist/schemas/platform/metadata/v1/credentials.schema.json

@@ -0,0 +1 @@
+{}

package/dist/schemas/platform/metadata/v1/messages.schema.json

@@ -0,0 +1,29 @@
+{
+  "required": [
+    "type"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "fetch"
+      ]
+    },
+    "object": {
+      "type": "object",
+      "oneOf": [
+        {
+          "$ref": "#/definitions/objectTypes/feed-parameters-url"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "objectTypes": {
+      "feed-parameters-url": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    }
+  }
+}

package/dist/schemas/platform/sockethub%3Ainternal/v1/credentials.schema.json

@@ -0,0 +1 @@
+{}

package/dist/schemas/platform/sockethub%3Ainternal/v1/messages.schema.json

@@ -0,0 +1 @@
+{}

package/dist/schemas/platform/xmpp/v1/credentials.schema.json

@@ -0,0 +1,43 @@
+{
+  "required": [
+    "object"
+  ],
+  "properties": {
+    "actor": {
+      "type": "object",
+      "required": [
+        "id"
+      ]
+    },
+    "object": {
+      "type": "object",
+      "required": [
+        "type",
+        "userAddress",
+        "password",
+        "resource"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "userAddress": {
+          "type": "string"
+        },
+        "password": {
+          "type": "string"
+        },
+        "server": {
+          "type": "string"
+        },
+        "port": {
+          "type": "number"
+        },
+        "resource": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/dist/schemas/platform/xmpp/v1/messages.schema.json

@@ -0,0 +1,21 @@
+{
+  "required": [
+    "type"
+  ],
+  "properties": {
+    "type": {
+      "enum": [
+        "connect",
+        "join",
+        "leave",
+        "send",
+        "update",
+        "request-friend",
+        "remove-friend",
+        "make-friend",
+        "query",
+        "disconnect"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sockethub/schemas",
   "description": "JSON schema files for validating Sockethub Activity Streams",
-  "version": "3.0.0-alpha.10",
+  "version": "3.0.0-alpha.12",
   "type": "module",
   "private": false,
   "author": "Nick Jennings <nick@silverbucket.net>",
@@ -15,6 +15,14 @@
       "bun": "./src/index.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./context": {
+      "bun": "./src/context.ts",
+      "import": "./dist/context.js",
+      "default": "./dist/context.js"
+    },
+    "./schemas/json/sockethub-config.json": {
+      "default": "./src/schemas/json/sockethub-config.json"
     }
   },
   "files": [
@@ -38,18 +46,17 @@
   },
   "homepage": "https://github.com/sockethub/sockethub/tree/master/packages/schemas",
   "devDependencies": {
-    "@types/bun": "latest",
-    "@types/debug": "^4.1.12"
+    "@types/bun": "latest"
   },
   "scripts": {
-    "build": "bun ./scripts/export-json-schema.ts && bun build src/index.ts --outdir dist --target node --format esm --sourcemap=external",
-    "clean": "rm -rf dist"
+    "build": "bun ./scripts/export-json-schema.ts && bun ./scripts/export-canonical-assets.ts && bun build src/index.ts src/context.ts --outdir dist --target node --format esm --sourcemap=external",
+    "clean": "rm -rf dist",
+    "clean:deps": "rm -rf node_modules"
   },
   "dependencies": {
     "ajv": "^8.17.1",
     "ajv-formats": "^2.1.1",
-    "ajv-formats-draft2019": "^1.6.1",
-    "debug": "^4.4.3"
+    "ajv-formats-draft2019": "^1.6.1"
   },
-  "gitHead": "8e1abf116b2a6b57d33c6e1a4af9143870517bae"
+  "gitHead": "f039dab3c3f67cbbf204476fc397532e973f82a8"
 }

package/src/context.ts

@@ -0,0 +1,125 @@
+import type { ActivityStream, JsonLdContext } from "./types.js";
+
+/**
+ * Canonical AS2 base vocabulary URL.
+ */
+export const AS2_BASE_CONTEXT_URL = "https://www.w3.org/ns/activitystreams";
+
+/**
+ * Sockethub base vocabulary URL for shared platform terms.
+ */
+export const SOCKETHUB_BASE_CONTEXT_URL =
+    "https://sockethub.org/ns/context/v1.jsonld";
+
+/**
+ * URL prefix for per-platform context URLs.
+ */
+export const PLATFORM_CONTEXT_PREFIX =
+    "https://sockethub.org/ns/context/platform/";
+
+/**
+ * Built-in pseudo-platform used for server-side error payloads.
+ */
+export const ERROR_PLATFORM_ID = "error";
+export const ERROR_PLATFORM_CONTEXT_URL =
+    "https://sockethub.org/ns/context/platform/error/v1.jsonld";
+
+/**
+ * Built-in pseudo-platform used for internal control messages.
+ */
+export const INTERNAL_PLATFORM_ID = "sockethub:internal";
+export const INTERNAL_PLATFORM_CONTEXT_URL =
+    "https://sockethub.org/ns/context/platform/sockethub:internal/v1.jsonld";
+
+const platformContextToPlatformId = new Map<string, string>();
+const platformContextToSchemaId = new Map<string, string>();
+const platformContextToCredentialsSchemaId = new Map<string, string>();
+
+/**
+ * Build the canonical Sockethub @context array for a platform context URL.
+ */
+export function buildCanonicalContext(
+    platformContextUrl: string,
+): JsonLdContext {
+    return [
+        AS2_BASE_CONTEXT_URL,
+        SOCKETHUB_BASE_CONTEXT_URL,
+        platformContextUrl,
+    ];
+}
+
+/**
+ * Normalize unknown @context input into a string-only array.
+ */
+function normalizeContextArray(value: unknown): Array<string> {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry): entry is string => typeof entry === "string");
+}
+
+/**
+ * Get a normalized @context array from an activity stream.
+ */
+export function getContextArray(msg: ActivityStream): Array<string> {
+    return normalizeContextArray(msg["@context"]);
+}
+
+/**
+ * Register a platform context URL and its schema IDs for runtime resolution.
+ */
+export function registerPlatformContext(
+    platformId: string,
+    platformContextUrl: string,
+    schemaId: string,
+    credentialsSchemaId: string,
+) {
+    platformContextToPlatformId.set(platformContextUrl, platformId);
+    platformContextToSchemaId.set(platformContextUrl, schemaId);
+    platformContextToCredentialsSchemaId.set(
+        platformContextUrl,
+        credentialsSchemaId,
+    );
+}
+
+/**
+ * Resolve the single registered platform context URL from a message.
+ * Returns null when there are zero or multiple registered platform contexts.
+ */
+export function resolvePlatformContextUrl(msg: ActivityStream): string | null {
+    const contexts = getContextArray(msg);
+    const matches = contexts.filter((contextUrl) =>
+        platformContextToPlatformId.has(contextUrl),
+    );
+    if (matches.length !== 1) {
+        return null;
+    }
+    return matches[0];
+}
+
+/**
+ * Resolve a platform ID from a platform context URL.
+ */
+export function getPlatformIdByContextUrl(
+    platformContextUrl: string,
+): string | undefined {
+    return platformContextToPlatformId.get(platformContextUrl);
+}
+
+/**
+ * Resolve a message schema ID from a platform context URL.
+ */
+export function getSchemaIdByContextUrl(
+    platformContextUrl: string,
+): string | undefined {
+    return platformContextToSchemaId.get(platformContextUrl);
+}
+
+/**
+ * Resolve a credentials schema ID from a platform context URL.
+ */
+export function getCredentialsSchemaIdByContextUrl(
+    platformContextUrl: string,
+): string | undefined {
+    return platformContextToCredentialsSchemaId.get(platformContextUrl);
+}

package/src/helpers/error-parser.ts

@@ -1,6 +1,10 @@
 import type { ErrorObject } from "ajv";
 import type { ActivityObject, ActivityStream } from "../types.js";
-import { ObjectTypesList } from "./objects.js";
+import { ActorTypesList, ObjectTypesList, TargetTypesList } from "./objects.js";
+
+export interface ValidationErrorOptions {
+    excludeTypes?: Array<string>;
+}
 
 interface TypeBreakdown {
     actor: Array<string>;
@@ -21,22 +25,28 @@ function parseMsg(error: ErrorObject): string {
 }
 
 function getTypeList(msg: ActivityStream | ActivityObject): Array<string> {
-    let types = [];
-    types.push(msg?.type);
-    for (const prop in msg) {
-        if (msg[prop]?.type) {
-            types = [...types, ...getTypeList(msg[prop])];
+    const types: Array<string> = [];
+    if (msg?.type) {
+        types.push(msg.type);
+    }
+    const record = msg as Record<string, unknown>;
+    for (const prop in record) {
+        const value = record[prop];
+        if (value && typeof value === "object" && "type" in value) {
+            types.push(
+                ...getTypeList(value as ActivityStream | ActivityObject),
+            );
         }
     }
     return types;
 }
 
-function getSchemaType(error: ErrorObject): string {
+function getSchemaType(error: ErrorObject): string | undefined {
     const schemaTypeRes = error.schemaPath.match(/#\/\w+\/\w+\/([\w-]+)\//);
     return schemaTypeRes ? schemaTypeRes[1] : undefined;
 }
 
-function getErrType(error: ErrorObject): string {
+function getErrType(error: ErrorObject): string | undefined {
     const errTypeRes = error.instancePath.match(/\/(\w+)/);
     return errTypeRes ? errTypeRes[1] : undefined;
 }
@@ -47,21 +57,33 @@ function getPartsCount(error: ErrorObject, types: TypeBreakdown): number {
     if (!errType) {
         return -1;
     }
-    if (!types[errType]) {
+    const typeList = (types as unknown as Record<string, Array<string>>)[
+        errType
+    ];
+    if (!typeList) {
         return -1;
     }
-    if (!types[errType].includes(schemaType)) {
+    if (!schemaType || !typeList.includes(schemaType)) {
         return -1;
     }
     const parts = error.instancePath.split("/");
     return parts.length;
 }
 
-function getTypes(msg: ActivityStream): TypeBreakdown {
+function getTypes(msg: ActivityStream | ActivityObject): TypeBreakdown {
+    if (!Array.isArray((msg as ActivityStream)["@context"])) {
+        return {
+            actor: [],
+            target: [],
+            object: getTypeList(msg),
+        };
+    }
+
+    const stream = msg as ActivityStream;
     return {
-        actor: getTypeList(msg.actor),
-        target: getTypeList(msg.target),
-        object: getTypeList(msg.context ? msg.object : msg),
+        actor: getTypeList(stream.actor),
+        target: getTypeList(stream.target),
+        object: stream.object ? getTypeList(stream.object) : [],
     };
 }
 
@@ -73,8 +95,9 @@ function getTypes(msg: ActivityStream): TypeBreakdown {
  * @returns {string}
  */
 export default function getErrorMessage(
-    msg,
+    msg: ActivityStream | ActivityObject,
     errors: Array<ErrorObject>,
+    options?: ValidationErrorOptions,
 ): string {
     const types = getTypes(msg);
     let deepest_entry = 0;
@@ -90,17 +113,41 @@ export default function getErrorMessage(
 
     return highest_depth >= 0
         ? parseMsg(errors[deepest_entry])
-        : composeFinalError(errors[errors.length - 1]);
+        : composeFinalError(errors[errors.length - 1], options);
 }
 
-function composeFinalError(error) {
+function filterTypeList(
+    types: Array<string>,
+    options?: ValidationErrorOptions,
+): Array<string> {
+    if (!options?.excludeTypes || options.excludeTypes.length === 0) {
+        return types;
+    }
+    const exclude = new Set(options.excludeTypes);
+    return types.filter((type) => !exclude.has(type));
+}
+
+function composeFinalError(
+    error: ErrorObject,
+    options?: ValidationErrorOptions,
+): string {
     // if we have yet to build an error message, assume this is an invalid type value (oneOf),
     // try to build a list of valid types
     let msg: string;
     if (error.keyword === "oneOf") {
+        const instanceRoot = error.instancePath.split("/")[1];
+        const pathScopedTypes =
+            instanceRoot === "actor"
+                ? ActorTypesList
+                : instanceRoot === "target"
+                  ? TargetTypesList
+                  : ObjectTypesList;
+        const filteredTypes = filterTypeList(pathScopedTypes, options);
+        const typesList =
+            filteredTypes.length > 0 ? filteredTypes : pathScopedTypes;
         msg =
             `${error.instancePath}: ${error.message}: ` +
-            `${ObjectTypesList.join(", ")}`;
+            `${typesList.join(", ")}`;
     } else {
         msg = `${
             error.instancePath ? error.instancePath : "activity stream"