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

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

@@ -6,74 +6,51 @@ export interface ASCollection {
     totalItems: number;
     items: Array<ActivityStream>;
 }
-
 export type JsonLdContext = Array<string>;
-
 export interface ActivityStream {
     "@context": JsonLdContext;
     id?: string;
     type: string;
-    platform?: 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>;
-
 export interface Logger {
     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 {
     log: Logger;
     sendToClient: PlatformSendToClient;
     updateActor: PlatformUpdateActor;
 }
-
 export interface CredentialsObject {
     "@context": JsonLdContext;
     type: "credentials";
@@ -84,7 +61,6 @@ export interface CredentialsObject {
     };
     target?: ActivityActor;
 }
-
 /**
  * Platform configuration discriminated union.
  *
@@ -103,17 +79,23 @@ export interface CredentialsObject {
  * - Example: IRC, XMPP
  */
 export type PlatformConfig = StatelessPlatformConfig | PersistentPlatformConfig;
-
 interface BasePlatformConfig {
     connectTimeoutMs?: number;
+    allowPrivateAddresses?: 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.
@@ -123,7 +105,6 @@ export interface PersistentPlatformConfig extends BasePlatformConfig {
     /** Message types requiring credentials (must be non-empty for persistent platforms) */
     requireCredentials: string[];
 }
-
 export interface PlatformSchemaStruct {
     name: string;
     version: string;
@@ -140,12 +121,13 @@ export interface PlatformSchemaStruct {
             };
         };
     };
+    responses?: object;
 }
-
 export interface PlatformConstructor {
-    new (session: PlatformSession): { log: Logger };
+    new (session: PlatformSession): {
+        log: Logger;
+    };
 }
-
 /**
  * Base interface for all Sockethub platforms.
  * Platforms implement protocol-specific logic for ActivityStreams messages.
@@ -167,7 +149,6 @@ export interface PlatformInterface {
     isInitialized(): boolean;
     cleanup(cb: PlatformCallback): void;
 }
-
 /**
  * Interface for persistent platforms with long-running connections.
  *
@@ -185,15 +166,6 @@ export interface PersistentPlatformInterface extends PlatformInterface {
      */
     credentialsHash: string | undefined;
     get config(): PersistentPlatformConfig;
-    connect(
-        job: ActivityStream,
-        credentials: CredentialsObject,
-        done: PlatformCallback,
-    ): void;
-}
-
-export interface PlatformSession {
-    log: Logger;
-    sendToClient: PlatformSendToClient;
-    updateActor: PlatformUpdateActor;
+    connect(job: ActivityStream, credentials: CredentialsObject, done: PlatformCallback): void;
 }
+export {};

package/dist/validator.d.ts

@@ -0,0 +1,26 @@
+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;
+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;
+export declare function validateCredentials(msg: ActivityStream): string;
+export declare function validatePlatformSchema(schema: Schema): string;
+export declare function addPlatformSchema(schema: Schema, platform_type: string): void;
+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.12",
+  "version": "3.0.0-alpha.13",
   "type": "module",
   "private": false,
   "author": "Nick Jennings <nick@silverbucket.net>",
@@ -12,25 +12,29 @@
   "main": "dist/index.js",
   "exports": {
     ".": {
-      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
     "./context": {
-      "bun": "./src/context.ts",
+      "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"
+    },
     "./schemas/json/sockethub-config.json": {
-      "default": "./src/schemas/json/sockethub-config.json"
+      "default": "./dist/schemas/json/sockethub-config.json"
     }
   },
   "files": [
-    "src/",
     "dist/"
   ],
   "engines": {
-    "bun": ">=1.2"
+    "node": ">=20"
   },
   "keywords": [
     "sockethub",
@@ -49,7 +53,7 @@
     "@types/bun": "latest"
   },
   "scripts": {
-    "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",
+    "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 --outdir dist --target browser --format esm --sourcemap=external",
     "clean": "rm -rf dist",
     "clean:deps": "rm -rf node_modules"
   },
@@ -58,5 +62,6 @@
     "ajv-formats": "^2.1.1",
     "ajv-formats-draft2019": "^1.6.1"
   },
-  "gitHead": "f039dab3c3f67cbbf204476fc397532e973f82a8"
+  "gitHead": "864733e5b34449ef39542eceb4ff11aa308081bc",
+  "types": "./dist/index.d.ts"
 }

package/src/context.ts

@@ -1,125 +0,0 @@
-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,160 +0,0 @@
-import type { ErrorObject } from "ajv";
-import type { ActivityObject, ActivityStream } from "../types.js";
-import { ActorTypesList, ObjectTypesList, TargetTypesList } from "./objects.js";
-
-export interface ValidationErrorOptions {
-    excludeTypes?: Array<string>;
-}
-
-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> {
-    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 | undefined {
-    const schemaTypeRes = error.schemaPath.match(/#\/\w+\/\w+\/([\w-]+)\//);
-    return schemaTypeRes ? schemaTypeRes[1] : undefined;
-}
-
-function getErrType(error: ErrorObject): string | undefined {
-    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;
-    }
-    const typeList = (types as unknown as Record<string, Array<string>>)[
-        errType
-    ];
-    if (!typeList) {
-        return -1;
-    }
-    if (!schemaType || !typeList.includes(schemaType)) {
-        return -1;
-    }
-    const parts = error.instancePath.split("/");
-    return parts.length;
-}
-
-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(stream.actor),
-        target: getTypeList(stream.target),
-        object: stream.object ? getTypeList(stream.object) : [],
-    };
-}
-
-/**
- * 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: ActivityStream | ActivityObject,
-    errors: Array<ErrorObject>,
-    options?: ValidationErrorOptions,
-): 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], options);
-}
-
-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}: ` +
-            `${typesList.join(", ")}`;
-    } else {
-        msg = `${
-            error.instancePath ? error.instancePath : "activity stream"
-        }: ${error.message}`;
-    }
-    if ("additionalProperty" in error.params) {
-        msg += `: ${error.params.additionalProperty}`;
-    }
-    return msg;
-}