@sockethub/schemas 3.0.0-alpha.9 → 3.0.0-beta.1

package/{src/types.ts → dist/types.d.ts}

@@ -1,77 +1,66 @@
 export interface ASCollection {
-    context: string;
+    "@context": JsonLdContext;
     id?: string;
     summary: string;
     type: "collection";
     totalItems: number;
     items: Array<ActivityStream>;
 }
-
+export type JsonLdContext = Array<string>;
 export interface ActivityStream {
+    "@context": JsonLdContext;
     id?: string;
     type: string;
-    context: string;
     actor: ActivityActor;
     object?: ActivityObject;
     target?: ActivityActor;
     error?: string;
 }
-
 export interface InternalActivityStream extends ActivityStream {
     sessionSecret?: string;
 }
-
 export interface BaseActivityObject {
     id?: string;
     type: string;
 }
-
 export interface ActivityActor extends BaseActivityObject {
     id: string;
     type: string;
     name?: string;
     [key: string]: unknown;
 }
-
 export interface ActivityObject extends BaseActivityObject {
     content?: string;
     [key: string]: unknown;
 }
-
 type ErrorMsg = string | Error;
-
-export type PlatformCallback = (
-    err?: ErrorMsg,
-    data?: ActivityStream | ASCollection,
-) => void;
-
+export type PlatformCallback = (err?: ErrorMsg, data?: ActivityStream | ASCollection) => void;
 export type CallbackInterface = (err?: ErrorMsg, data?: unknown) => void;
-
 export type MiddlewareCallback = (data: ActivityStream | Error) => void;
-
 export type CompletedJobHandler = (data: ActivityStream | undefined) => void;
-
-export type PlatformSendToClient = (
-    msg: ActivityStream,
-    special?: string,
-) => void;
-
+export type PlatformSendToClient = (msg: ActivityStream, special?: string) => void;
 export type PlatformUpdateActor = (credentials: object) => Promise<void>;
-
+/**
+ * Read-only check that a proposed actor rename will not overwrite a different
+ * account. IRC calls this before sending NICK: the refusal has to happen
+ * before the server applies the nick, or a collision still changes the nick
+ * the connection is using while the client is told the rename failed.
+ */
+export type PlatformPrepareActorUpdate = (credentials: object) => Promise<void>;
 export interface Logger {
-    // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-    // biome-ignore lint/style/useShorthandFunctionType: <explanation>
-    (msg: string, data?: any): void;
+    error(message: string, meta?: object): void;
+    warn(message: string, meta?: object): void;
+    info(message: string, meta?: object): void;
+    debug(message: string, meta?: object): void;
 }
-
 export interface PlatformSession {
-    debug: Logger;
+    log: Logger;
     sendToClient: PlatformSendToClient;
     updateActor: PlatformUpdateActor;
+    prepareActorUpdate?: PlatformPrepareActorUpdate;
 }
-
 export interface CredentialsObject {
-    context: string;
+    "@context": JsonLdContext;
     type: "credentials";
     actor: ActivityActor;
     object: {
@@ -80,7 +69,6 @@ export interface CredentialsObject {
     };
     target?: ActivityActor;
 }
-
 /**
  * Platform configuration discriminated union.
  *
@@ -99,17 +87,25 @@ export interface CredentialsObject {
  * - Example: IRC, XMPP
  */
 export type PlatformConfig = StatelessPlatformConfig | PersistentPlatformConfig;
-
 interface BasePlatformConfig {
     connectTimeoutMs?: number;
+    allowPrivateAddresses?: boolean;
+    /** CalDAV-only escape hatch for explicitly configured HTTP services. */
+    allowInsecureHttp?: boolean;
 }
-
 /** Configuration for stateless platforms that start/stop per-request */
 export interface StatelessPlatformConfig extends BasePlatformConfig {
     persist: false;
     requireCredentials?: string[];
+    /**
+     * Number of jobs the platform's worker processes in parallel. Stateless
+     * platforms are shared by every session on the server, so serial
+     * processing lets one slow job (e.g. a hanging feed fetch) stall all
+     * other clients. Defaults to 10; override per-platform via
+     * `packageConfig`.
+     */
+    concurrency?: number;
 }
-
 /**
  * Configuration for persistent platforms with long-running connections.
  * These always require credentials because persistent state is actor-specific.
@@ -118,13 +114,14 @@ export interface PersistentPlatformConfig extends BasePlatformConfig {
     persist: true;
     /** Message types requiring credentials (must be non-empty for persistent platforms) */
     requireCredentials: string[];
-    /** Whether the platform has completed initialization */
-    initialized: boolean;
 }
-
 export interface PlatformSchemaStruct {
     name: string;
     version: string;
+    contextUrl: string;
+    contextVersion: string;
+    schemaVersion: string;
+    messageConstraints?: object;
     credentials?: object;
     messages?: {
         required?: string[];
@@ -134,23 +131,34 @@ export interface PlatformSchemaStruct {
             };
         };
     };
+    responses?: object;
 }
-
 export interface PlatformConstructor {
-    new (session: PlatformSession): { debug: Logger };
+    new (session: PlatformSession): {
+        log: Logger;
+    };
 }
-
 /**
  * Base interface for all Sockethub platforms.
  * Platforms implement protocol-specific logic for ActivityStreams messages.
  */
 export interface PlatformInterface {
-    debug: Logger;
     get config(): PlatformConfig;
     get schema(): PlatformSchemaStruct;
+    /**
+     * Returns whether the platform is ready to handle jobs.
+     *
+     * For persistent platforms: Returns true once the initial connection succeeds.
+     * During temporary network interruptions with automatic reconnection, should
+     * remain true to allow queued jobs to retry rather than fail.
+     *
+     * For stateless platforms: Can always return true since they have no connection state.
+     *
+     * @returns true if the platform can process jobs, false otherwise
+     */
+    isInitialized(): boolean;
     cleanup(cb: PlatformCallback): void;
 }
-
 /**
  * Interface for persistent platforms with long-running connections.
  *
@@ -168,15 +176,6 @@ export interface PersistentPlatformInterface extends PlatformInterface {
      */
     credentialsHash: string | undefined;
     get config(): PersistentPlatformConfig;
-    connect(
-        job: ActivityStream,
-        credentials: CredentialsObject,
-        done: PlatformCallback,
-    ): void;
-}
-
-export interface PlatformSession {
-    debug: Logger;
-    sendToClient: PlatformSendToClient;
-    updateActor: PlatformUpdateActor;
+    connect(job: ActivityStream, credentials: CredentialsObject, done: PlatformCallback): void;
 }
+export {};

package/dist/validator.d.ts

@@ -0,0 +1,50 @@
+import { type Schema } from "ajv";
+import { type ValidationErrorOptions } from "./helpers/error-parser.js";
+import type { ActivityStream } from "./types.js";
+export declare function registerSystemPlatformContexts(): void;
+export declare function setValidationErrorOptions(options: ValidationErrorOptions): void;
+/**
+ * Validate a (fully-materialized) Sockethub server config object against the
+ * canonical config schema. Returns "" when valid, otherwise a human-readable
+ * error string. Used by the server at startup so a mis-typed or unknown config
+ * value — including inside a platform's `packageConfig` entry — fails loudly
+ * rather than reaching a platform wrong-typed.
+ */
+export declare function validateSockethubConfig(config: unknown): string;
+/**
+ * Validate an inbound activity stream against the shared envelope and its
+ * registered platform message schema. Returns "" when valid; skipped (also "")
+ * when code generation is unavailable.
+ */
+export declare function validateActivityStream(msg: ActivityStream): string;
+/**
+ * Validate an outbound platform response against that platform's `responses`
+ * schema. Returns "" when the platform has no responses schema registered (yet),
+ * so outbound validation can be adopted platform-by-platform.
+ */
+export declare function validateActivityStreamResponse(msg: ActivityStream): string;
+/**
+ * Validate a credentials activity stream against the shared envelope and its
+ * registered platform credentials schema. Returns "" when valid; skipped (also
+ * "") when code generation is unavailable.
+ */
+export declare function validateCredentials(msg: ActivityStream): string;
+/**
+ * Validate a platform schema: its structural shape via Ajv (when available)
+ * and that its actor/target types are registered in the shared ActivityStreams
+ * envelope. Returns "" when valid, otherwise an error string.
+ */
+export declare function validatePlatformSchema(schema: Schema): string;
+/**
+ * Register a platform's message or credentials schema with the validators, so
+ * local validation uses the same canonical sources as the server. No-op when
+ * code generation is unavailable.
+ */
+export declare function addPlatformSchema(schema: Schema, platform_type: string): void;
+/**
+ * Look up a registered platform schema validator, or `undefined` when no such
+ * schema is registered or code generation is unavailable.
+ */
+export declare function getPlatformSchema(platform_type: string): import("ajv/dist/core.js").AnyValidateFunction<unknown>;
+export declare function addPlatformContext(platformId: string, platformContextUrl: string): void;
+export declare function resolvePlatformId(msg: ActivityStream): string | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sockethub/schemas",
   "description": "JSON schema files for validating Sockethub Activity Streams",
-  "version": "3.0.0-alpha.9",
+  "version": "3.0.0-beta.1",
   "type": "module",
   "private": false,
   "author": "Nick Jennings <nick@silverbucket.net>",
@@ -12,17 +12,38 @@
   "main": "dist/index.js",
   "exports": {
     ".": {
-      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./context": {
+      "types": "./dist/context.d.ts",
+      "import": "./dist/context.js",
+      "default": "./dist/context.js"
+    },
+    "./object-types": {
+      "types": "./dist/object-types.d.ts",
+      "import": "./dist/object-types.js",
+      "default": "./dist/object-types.js"
+    },
+    "./service-descriptor": {
+      "types": "./dist/service-descriptor.d.ts",
+      "bun": "./src/service-descriptor.ts",
+      "import": "./dist/service-descriptor.js",
+      "default": "./dist/service-descriptor.js"
+    },
+    "./schemas/json/sockethub-config.json": {
+      "default": "./dist/schemas/json/sockethub-config.json"
+    },
+    "./schemas/json/service-descriptor.json": {
+      "default": "./dist/schemas/json/service-descriptor.json"
     }
   },
   "files": [
-    "src/",
     "dist/"
   ],
   "engines": {
-    "bun": ">=1.2"
+    "node": ">=20"
   },
   "keywords": [
     "sockethub",
@@ -38,18 +59,18 @@
   },
   "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/object-types.ts --outdir dist --target node --format esm --sourcemap=external && bun build src/context.ts src/activity-stream-helper.ts src/service-descriptor.ts --outdir dist --target browser --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": "b89aac0946735864f3fec3bdc4ea15328b37120e"
+  "gitHead": "928f0c480e4828f492fb29a97712474a8f1bcaef",
+  "types": "./dist/index.d.ts"
 }

package/src/helpers/error-parser.ts

@@ -1,113 +0,0 @@
-import type { ErrorObject } from "ajv";
-import type { ActivityObject, ActivityStream } from "../types.js";
-import { ObjectTypesList } from "./objects.js";
-
-interface TypeBreakdown {
-    actor: Array<string>;
-    object: Array<string>;
-    target: Array<string>;
-}
-
-function parseMsg(error: ErrorObject): string {
-    let err = `${
-        error.instancePath ? error.instancePath : "activity stream"
-    }: ${error.message}`;
-    if (error.keyword === "additionalProperties") {
-        err += `: ${error.params.additionalProperty}`;
-    } else if (error.keyword === "enum") {
-        err += `: ${error.params.allowedValues.join(", ")}`;
-    }
-    return err;
-}
-
-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])];
-        }
-    }
-    return types;
-}
-
-function getSchemaType(error: ErrorObject): string {
-    const schemaTypeRes = error.schemaPath.match(/#\/\w+\/\w+\/([\w-]+)\//);
-    return schemaTypeRes ? schemaTypeRes[1] : undefined;
-}
-
-function getErrType(error: ErrorObject): string {
-    const errTypeRes = error.instancePath.match(/\/(\w+)/);
-    return errTypeRes ? errTypeRes[1] : undefined;
-}
-
-function getPartsCount(error: ErrorObject, types: TypeBreakdown): number {
-    const schemaType = getSchemaType(error);
-    const errType = getErrType(error);
-    if (!errType) {
-        return -1;
-    }
-    if (!types[errType]) {
-        return -1;
-    }
-    if (!types[errType].includes(schemaType)) {
-        return -1;
-    }
-    const parts = error.instancePath.split("/");
-    return parts.length;
-}
-
-function getTypes(msg: ActivityStream): TypeBreakdown {
-    return {
-        actor: getTypeList(msg.actor),
-        target: getTypeList(msg.target),
-        object: getTypeList(msg.context ? msg.object : msg),
-    };
-}
-
-/**
- * Traverses the errors array from ajv, and makes a series of filtering decisions to
- * try to arrive at the most useful error.
- * @param msg
- * @param errors
- * @returns {string}
- */
-export default function getErrorMessage(
-    msg,
-    errors: Array<ErrorObject>,
-): string {
-    const types = getTypes(msg);
-    let deepest_entry = 0;
-    let highest_depth = -1;
-
-    for (let i = 0; i < errors.length; i++) {
-        const partsCount = getPartsCount(errors[i], types);
-        if (partsCount > highest_depth) {
-            highest_depth = partsCount;
-            deepest_entry = i;
-        }
-    }
-
-    return highest_depth >= 0
-        ? parseMsg(errors[deepest_entry])
-        : composeFinalError(errors[errors.length - 1]);
-}
-
-function composeFinalError(error) {
-    // 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") {
-        msg =
-            `${error.instancePath}: ${error.message}: ` +
-            `${ObjectTypesList.join(", ")}`;
-    } else {
-        msg = `${
-            error.instancePath ? error.instancePath : "activity stream"
-        }: ${error.message}`;
-    }
-    if ("additionalProperty" in error.params) {
-        msg += `: ${error.params.additionalProperty}`;
-    }
-    return msg;
-}

package/src/helpers/objects.ts

@@ -1,227 +0,0 @@
-export const validObjectRefs = [];
-export const validObjectDefs = {};
-
-export const ObjectTypesSchema = {
-    credentials: {
-        required: ["type"],
-        additionalProperties: true,
-        properties: {
-            type: {
-                enum: ["credentials"],
-            },
-        },
-    },
-
-    feed: {
-        required: ["id", "type"],
-        additionalProperties: true,
-        properties: {
-            type: {
-                enum: ["feed"],
-            },
-            id: {
-                type: "string",
-                format: "iri",
-            },
-            name: {
-                type: "string",
-            },
-            description: {
-                type: "string",
-            },
-            author: {
-                type: "string",
-            },
-            favicon: {
-                type: "string",
-            },
-        },
-    },
-
-    message: {
-        required: ["type", "content"],
-        additionalProperties: true,
-        properties: {
-            type: {
-                enum: ["message"],
-            },
-            id: {
-                type: "string",
-            },
-            name: {
-                type: "string",
-            },
-            content: {
-                type: "string",
-            },
-        },
-    },
-
-    me: {
-        required: ["type", "content"],
-        additionalProperties: true,
-        properties: {
-            type: {
-                enum: ["me"],
-            },
-            content: {
-                type: "string",
-            },
-        },
-    },
-
-    person: {
-        required: ["id", "type"],
-        additionalProperties: true,
-        properties: {
-            id: {
-                type: "string",
-            },
-            type: {
-                enum: ["person"],
-            },
-            name: {
-                type: "string",
-            },
-        },
-    },
-
-    room: {
-        required: ["id", "type"],
-        additionalProperties: true,
-        properties: {
-            id: {
-                type: "string",
-            },
-            type: {
-                enum: ["room"],
-            },
-            name: {
-                type: "string",
-            },
-        },
-    },
-
-    service: {
-        required: ["id", "type"],
-        additionalProperties: true,
-        properties: {
-            id: {
-                type: "string",
-            },
-            type: {
-                enum: ["service"],
-            },
-            name: {
-                type: "string",
-            },
-        },
-    },
-
-    website: {
-        required: ["id", "type"],
-        additionalProperties: true,
-        properties: {
-            id: {
-                type: "string",
-                format: "iri",
-            },
-            type: {
-                enum: ["website"],
-            },
-            name: {
-                type: "string",
-            },
-        },
-    },
-
-    attendance: {
-        required: ["type"],
-        additionalProperties: false,
-        properties: {
-            type: {
-                enum: ["attendance"],
-            },
-            members: {
-                type: "array",
-                items: {
-                    type: "string",
-                },
-            },
-        },
-    },
-
-    presence: {
-        required: ["type"],
-        additionalProperties: false,
-        properties: {
-            type: {
-                enum: ["presence"],
-            },
-            presence: {
-                enum: ["away", "chat", "dnd", "xa", "offline", "online"],
-            },
-            role: {
-                enum: ["owner", "member", "participant", "admin"],
-            },
-            content: {
-                type: "string",
-            },
-        },
-    },
-
-    // inspired by https://www.w3.org/ns/activitystreams#Relationship
-    relationship: {
-        required: ["type", "relationship"],
-        additionalProperties: false,
-        properties: {
-            type: {
-                enum: ["relationship"],
-            },
-            relationship: {
-                enum: ["role"],
-            },
-            subject: {
-                type: "object",
-                oneOf: [{ $ref: "#/definitions/type/presence" }],
-            },
-            object: {
-                type: "object",
-                oneOf: validObjectRefs,
-            },
-        },
-    },
-
-    topic: {
-        required: ["type"],
-        additionalProperties: false,
-        properties: {
-            type: {
-                enum: ["topic"],
-            },
-            content: {
-                type: "string",
-            },
-        },
-    },
-
-    address: {
-        required: ["type"],
-        additionalProperties: false,
-        properties: {
-            type: {
-                enum: ["address"],
-            },
-        },
-    },
-};
-
-export const ObjectTypesList = Object.keys(ObjectTypesSchema);
-
-for (const type of ObjectTypesList) {
-    if (type === "credentials") {
-        continue;
-    }
-    validObjectRefs.push({ $ref: `#/definitions/type/${type}` });
-    validObjectDefs[type] = ObjectTypesSchema[type];
-}