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

package/src/schemas/json/activity-stream.json

@@ -1,34 +1,42 @@
 {
-	"$id": "https://sockethub.org/schemas/3.0.0-alpha.11/activity-stream.json",
+	"$id": "https://sockethub.org/schemas/3.0.0-alpha.12/activity-stream.json",
 	"description": "Schema for Sockethub Activity Streams",
 	"type": "object",
 	"required": [
-		"context",
+		"@context",
 		"type",
 		"actor"
 	],
 	"properties": {
+		"@context": {
+			"type": "array",
+			"minItems": 3,
+			"maxItems": 3,
+			"items": {
+				"type": "string"
+			},
+			"allOf": [
+				{
+					"contains": {
+						"const": "https://www.w3.org/ns/activitystreams"
+					}
+				},
+				{
+					"contains": {
+						"const": "https://sockethub.org/ns/context/v1.jsonld"
+					}
+				}
+			]
+		},
 		"id": {
 			"type": "string"
 		},
 		"type": {
 			"type": "string"
 		},
-		"context": {
-			"type": "string"
-		},
 		"actor": {
 			"type": "object",
 			"oneOf": [
-				{
-					"$ref": "#/definitions/type/feed"
-				},
-				{
-					"$ref": "#/definitions/type/message"
-				},
-				{
-					"$ref": "#/definitions/type/me"
-				},
 				{
 					"$ref": "#/definitions/type/person"
 				},
@@ -39,37 +47,19 @@
 					"$ref": "#/definitions/type/service"
 				},
 				{
-					"$ref": "#/definitions/type/website"
-				},
-				{
-					"$ref": "#/definitions/type/attendance"
-				},
-				{
-					"$ref": "#/definitions/type/presence"
-				},
-				{
-					"$ref": "#/definitions/type/relationship"
+					"$ref": "#/definitions/type/feed"
 				},
 				{
-					"$ref": "#/definitions/type/topic"
+					"$ref": "#/definitions/type/website"
 				},
 				{
-					"$ref": "#/definitions/type/address"
+					"$ref": "#/definitions/type/platform"
 				}
 			]
 		},
 		"target": {
 			"type": "object",
 			"oneOf": [
-				{
-					"$ref": "#/definitions/type/feed"
-				},
-				{
-					"$ref": "#/definitions/type/message"
-				},
-				{
-					"$ref": "#/definitions/type/me"
-				},
 				{
 					"$ref": "#/definitions/type/person"
 				},
@@ -80,19 +70,13 @@
 					"$ref": "#/definitions/type/service"
 				},
 				{
-					"$ref": "#/definitions/type/website"
-				},
-				{
-					"$ref": "#/definitions/type/attendance"
-				},
-				{
-					"$ref": "#/definitions/type/presence"
+					"$ref": "#/definitions/type/feed"
 				},
 				{
-					"$ref": "#/definitions/type/relationship"
+					"$ref": "#/definitions/type/website"
 				},
 				{
-					"$ref": "#/definitions/type/topic"
+					"$ref": "#/definitions/type/platform"
 				},
 				{
 					"$ref": "#/definitions/type/address"
@@ -123,6 +107,9 @@
 				{
 					"$ref": "#/definitions/type/service"
 				},
+				{
+					"$ref": "#/definitions/type/platform"
+				},
 				{
 					"$ref": "#/definitions/type/website"
 				},
@@ -140,6 +127,9 @@
 				},
 				{
 					"$ref": "#/definitions/type/address"
+				},
+				{
+					"$ref": "#/definitions/type/heartbeat"
 				}
 			]
 		},
@@ -293,6 +283,26 @@
 					}
 				}
 			},
+			"platform": {
+				"required": [
+					"id",
+					"type"
+				],
+				"additionalProperties": true,
+				"properties": {
+					"id": {
+						"type": "string"
+					},
+					"type": {
+						"enum": [
+							"platform"
+						]
+					},
+					"name": {
+						"type": "string"
+					}
+				}
+			},
 			"website": {
 				"required": [
 					"id",
@@ -413,6 +423,9 @@
 							{
 								"$ref": "#/definitions/type/service"
 							},
+							{
+								"$ref": "#/definitions/type/platform"
+							},
 							{
 								"$ref": "#/definitions/type/website"
 							},
@@ -430,6 +443,9 @@
 							},
 							{
 								"$ref": "#/definitions/type/address"
+							},
+							{
+								"$ref": "#/definitions/type/heartbeat"
 							}
 						]
 					}
@@ -463,6 +479,23 @@
 						]
 					}
 				}
+			},
+			"heartbeat": {
+				"required": [
+					"type",
+					"timestamp"
+				],
+				"additionalProperties": false,
+				"properties": {
+					"type": {
+						"enum": [
+							"heartbeat"
+						]
+					},
+					"timestamp": {
+						"type": "number"
+					}
+				}
 			}
 		}
 	}

package/src/schemas/json/platform.json

@@ -1,13 +1,33 @@
 {
-	"$id": "https://sockethub.org/schemas/3.0.0-alpha.11/platform.json",
+	"$id": "https://sockethub.org/schemas/3.0.0-alpha.12/platform.json",
 	"type": "object",
 	"required": [
 		"name",
 		"version",
-		"messages"
+		"messages",
+		"contextUrl",
+		"contextVersion",
+		"schemaVersion"
 	],
 	"additionalProperties": false,
 	"properties": {
+		"contextUrl": {
+			"title": "contextUrl",
+			"type": "string",
+			"format": "uri"
+		},
+		"contextVersion": {
+			"title": "contextVersion",
+			"type": "string"
+		},
+		"schemaVersion": {
+			"title": "schemaVersion",
+			"type": "string"
+		},
+		"messageConstraints": {
+			"title": "messageConstraints",
+			"type": "object"
+		},
 		"credentials": {
 			"title": "credentials",
 			"type": "object"

package/src/schemas/json/sockethub-config.json

@@ -1,5 +1,5 @@
 {
-	"$id": "https://sockethub.org/schemas/3.0.0-alpha.11/sockethub-config.json",
+	"$id": "https://sockethub.org/schemas/3.0.0-alpha.12/sockethub-config.json",
 	"description": "Sockethub Config Schema",
 	"type": "object",
 	"required": [
@@ -217,6 +217,20 @@
 					"default": "/sockethub"
 				}
 			}
+		},
+		"platformHeartbeat": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"intervalMs": {
+					"type": "number",
+					"default": 5000
+				},
+				"timeoutMs": {
+					"type": "number",
+					"default": 15000
+				}
+			}
 		}
 	}
 }

package/src/schemas/platform.ts

@@ -21,9 +21,33 @@
 export const PlatformSchema = {
     $id: "https://sockethub.org/schemas/v/platform.json",
     type: "object",
-    required: ["name", "version", "messages"],
+    required: [
+        "name",
+        "version",
+        "messages",
+        "contextUrl",
+        "contextVersion",
+        "schemaVersion",
+    ],
     additionalProperties: false,
     properties: {
+        contextUrl: {
+            title: "contextUrl",
+            type: "string",
+            format: "uri",
+        },
+        contextVersion: {
+            title: "contextVersion",
+            type: "string",
+        },
+        schemaVersion: {
+            title: "schemaVersion",
+            type: "string",
+        },
+        messageConstraints: {
+            title: "messageConstraints",
+            type: "object",
+        },
         credentials: {
             title: "credentials",
             type: "object",

package/src/schemas/sockethub-config.ts

@@ -164,7 +164,7 @@ export const SockethubConfigSchema = {
                 },
                 maxRetriesPerRequest: {
                     type: ["number", "null"],
-                    default: null,
+                    default: null as number | null,
                     description:
                         "Maximum number of retries per request (null for BullMQ default)",
                 },
@@ -202,5 +202,19 @@ export const SockethubConfigSchema = {
                 },
             },
         },
+        platformHeartbeat: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                intervalMs: {
+                    type: "number",
+                    default: 5000,
+                },
+                timeoutMs: {
+                    type: "number",
+                    default: 15000,
+                },
+            },
+        },
     },
 };

package/src/types/ajv-formats-draft2019.d.ts

@@ -0,0 +1,5 @@
+declare module "ajv-formats-draft2019" {
+    import type Ajv from "ajv";
+    const addFormats: (ajv: Ajv) => void;
+    export default addFormats;
+}

package/src/types.ts

@@ -1,5 +1,5 @@
 export interface ASCollection {
-    context: string;
+    "@context": JsonLdContext;
     id?: string;
     summary: string;
     type: "collection";
@@ -7,10 +7,13 @@ export interface ASCollection {
     items: Array<ActivityStream>;
 }
 
+export type JsonLdContext = Array<string>;
+
 export interface ActivityStream {
+    "@context": JsonLdContext;
     id?: string;
     type: string;
-    context: string;
+    platform?: string;
     actor: ActivityActor;
     object?: ActivityObject;
     target?: ActivityActor;
@@ -72,7 +75,7 @@ export interface PlatformSession {
 }
 
 export interface CredentialsObject {
-    context: string;
+    "@context": JsonLdContext;
     type: "credentials";
     actor: ActivityActor;
     object: {
@@ -124,6 +127,10 @@ export interface PersistentPlatformConfig extends BasePlatformConfig {
 export interface PlatformSchemaStruct {
     name: string;
     version: string;
+    contextUrl: string;
+    contextVersion: string;
+    schemaVersion: string;
+    messageConstraints?: object;
     credentials?: object;
     messages?: {
         required?: string[];

package/src/validator.ts

@@ -1,22 +1,35 @@
 import Ajv, { type Schema } from "ajv";
 import addFormats from "ajv-formats";
 import additionsFormats2019 from "ajv-formats-draft2019";
-import getErrorMessage from "./helpers/error-parser.js";
+import {
+    ERROR_PLATFORM_CONTEXT_URL,
+    ERROR_PLATFORM_ID,
+    getCredentialsSchemaIdByContextUrl,
+    getPlatformIdByContextUrl,
+    getSchemaIdByContextUrl,
+    INTERNAL_PLATFORM_CONTEXT_URL,
+    INTERNAL_PLATFORM_ID,
+    registerPlatformContext,
+    resolvePlatformContextUrl,
+} from "./context.js";
+import getErrorMessage, {
+    type ValidationErrorOptions,
+} from "./helpers/error-parser.js";
 import { ActivityObjectSchema } from "./schemas/activity-object.js";
 import { ActivityStreamSchema } from "./schemas/activity-stream.js";
 import { PlatformSchema } from "./schemas/platform.js";
-import type { ActivityStream } from "./types.js";
+import type { ActivityObject, ActivityStream } from "./types.js";
 
 const ajv = new Ajv({ strictTypes: false, allErrors: true });
-addFormats(ajv);
-additionsFormats2019(ajv);
+addFormats(ajv as unknown as Parameters<typeof addFormats>[0]);
+additionsFormats2019(ajv as unknown as Ajv);
 
-interface SchemasDict {
-    string?: Schema;
-}
+type SchemasDict = Record<string, Schema>;
 
 const schemaURL = "https://sockethub.org/schemas/v0";
 const schemas: SchemasDict = {};
+let validationErrorOptions: ValidationErrorOptions = {};
+let systemContextsRegistered = false;
 
 schemas[`${schemaURL}/activity-stream`] = ActivityStreamSchema;
 schemas[`${schemaURL}/activity-object`] = ActivityObjectSchema;
@@ -25,12 +38,45 @@ for (const uri in schemas) {
     ajv.addSchema(schemas[uri], uri);
 }
 
+function registerSystemContext(platformId: string, contextUrl: string): void {
+    registerPlatformContext(
+        platformId,
+        contextUrl,
+        `${schemaURL}/context/${platformId}/messages`,
+        `${schemaURL}/context/${platformId}/credentials`,
+    );
+
+    const messageSchemaRef = `${schemaURL}/context/${platformId}/messages`;
+    if (!ajv.getSchema(messageSchemaRef)) {
+        ajv.addSchema({}, messageSchemaRef);
+    }
+
+    const credentialsSchemaRef = `${schemaURL}/context/${platformId}/credentials`;
+    if (!ajv.getSchema(credentialsSchemaRef)) {
+        ajv.addSchema({}, credentialsSchemaRef);
+    }
+}
+
+export function registerSystemPlatformContexts(): void {
+    if (systemContextsRegistered) {
+        return;
+    }
+    registerSystemContext(ERROR_PLATFORM_ID, ERROR_PLATFORM_CONTEXT_URL);
+    registerSystemContext(INTERNAL_PLATFORM_ID, INTERNAL_PLATFORM_CONTEXT_URL);
+    systemContextsRegistered = true;
+}
+
+registerSystemPlatformContexts();
+
 function handleValidation(
     schemaRef: string,
-    msg: ActivityStream,
+    msg: ActivityStream | ActivityObject,
     isObject = false,
 ): string {
     const validator = ajv.getSchema(schemaRef);
+    if (!validator) {
+        return `schema ${schemaRef} not found`;
+    }
     let result: boolean | Promise<unknown>;
     if (isObject) {
         result = validator({ object: msg });
@@ -38,34 +84,81 @@ function handleValidation(
         result = validator(msg);
     }
     if (!result) {
-        let errorMessage = getErrorMessage(msg, validator.errors);
-        if (msg.context) {
-            errorMessage = `[${msg.context}] ${errorMessage}`;
+        let errorMessage = getErrorMessage(
+            msg,
+            validator.errors,
+            validationErrorOptions,
+        );
+        if (Array.isArray((msg as ActivityStream)["@context"])) {
+            const platformContextUrl = resolvePlatformContextUrl(
+                msg as ActivityStream,
+            );
+            if (platformContextUrl) {
+                const platformId =
+                    getPlatformIdByContextUrl(platformContextUrl);
+                if (platformId) {
+                    errorMessage = `[${platformId}] ${errorMessage}`;
+                }
+            }
         }
         return errorMessage;
     }
     return "";
 }
 
-export function validateActivityObject(msg: ActivityStream): string {
+export function setValidationErrorOptions(
+    options: ValidationErrorOptions,
+): void {
+    validationErrorOptions = { ...validationErrorOptions, ...options };
+}
+
+export function validateActivityObject(msg: ActivityObject): string {
     return handleValidation(`${schemaURL}/activity-object`, msg, true);
 }
 
 export function validateActivityStream(msg: ActivityStream): string {
-    return handleValidation(`${schemaURL}/activity-stream`, msg);
+    const streamValidationError = handleValidation(
+        `${schemaURL}/activity-stream`,
+        msg,
+    );
+    if (streamValidationError) {
+        return streamValidationError;
+    }
+    const platformContextUrl = resolvePlatformContextUrl(msg);
+    if (!platformContextUrl) {
+        return "activity streams must have exactly one registered platform context URL in @context";
+    }
+    const schemaId = getSchemaIdByContextUrl(platformContextUrl);
+    if (!schemaId) {
+        return `platform context URL ${platformContextUrl} does not have a registered message schema`;
+    }
+    return handleValidation(schemaId, msg);
 }
 
 export function validateCredentials(msg: ActivityStream): string {
-    if (!msg.context) {
-        return "credential activity streams must have a context set";
+    if (!Array.isArray(msg["@context"])) {
+        return "credential activity streams must have an @context set";
     }
     if (msg.type !== "credentials") {
         return "credential activity streams must have credentials set as type";
     }
-    return handleValidation(
-        `${schemaURL}/context/${msg.context}/credentials`,
+    const streamValidationError = handleValidation(
+        `${schemaURL}/activity-stream`,
         msg,
     );
+    if (streamValidationError) {
+        return streamValidationError;
+    }
+    const platformContextUrl = resolvePlatformContextUrl(msg);
+    if (!platformContextUrl) {
+        return "credential activity streams must have exactly one registered platform context URL in @context";
+    }
+    const credentialsSchemaId =
+        getCredentialsSchemaIdByContextUrl(platformContextUrl);
+    if (!credentialsSchemaId) {
+        return `platform context URL ${platformContextUrl} does not have a registered credentials schema`;
+    }
+    return handleValidation(credentialsSchemaId, msg);
 }
 
 export function validatePlatformSchema(schema: Schema): string {
@@ -79,9 +172,36 @@ export function validatePlatformSchema(schema: Schema): string {
 }
 
 export function addPlatformSchema(schema: Schema, platform_type: string) {
-    ajv.addSchema(schema, `${schemaURL}/context/${platform_type}`);
+    const schemaRef = `${schemaURL}/context/${platform_type}`;
+    if (!ajv.getSchema(schemaRef)) {
+        ajv.addSchema(schema, schemaRef);
+    }
 }
 
 export function getPlatformSchema(platform_type: string) {
     return ajv.getSchema(`${schemaURL}/context/${platform_type}`);
 }
+
+export function addPlatformContext(
+    platformId: string,
+    platformContextUrl: string,
+) {
+    registerPlatformContext(
+        platformId,
+        platformContextUrl,
+        `${schemaURL}/context/${platformId}/messages`,
+        `${schemaURL}/context/${platformId}/credentials`,
+    );
+}
+
+export function resolvePlatformId(msg: ActivityStream): string | null {
+    const platformContextUrl = resolvePlatformContextUrl(msg);
+    if (platformContextUrl) {
+        const id = getPlatformIdByContextUrl(platformContextUrl);
+        if (id) return id;
+    }
+    if (typeof msg.platform === "string" && msg.platform) {
+        return msg.platform;
+    }
+    return null;
+}