@kittymi/openclaw-generic-http 0.1.3

package/dist/inbound/validator.js

@@ -0,0 +1,114 @@
+import { ERROR_CODES } from "../errors/codes.js";
+import { GenericHttpPluginError } from "../errors/exceptions.js";
+import { normalizeAttachment } from "../protocol/attachments.js";
+const CONVERSATION_TYPES = new Set(["dm", "group", "room", "ticket"]);
+const SENDER_TYPES = new Set(["user", "bot", "system"]);
+const ATTACHMENT_KINDS = new Set(["file", "image"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new GenericHttpPluginError(ERROR_CODES.MISSING_REQUIRED_FIELD, `Field "${field}" must be a non-empty string.`, { field });
+    }
+}
+function validateOptionalString(value, field) {
+    if (value !== undefined && value !== null && typeof value !== "string") {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_FIELD_FORMAT, `Field "${field}" must be a string when provided.`, { field });
+    }
+}
+function validateMetadata(value, field) {
+    if (value !== undefined && !isRecord(value)) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_FIELD_FORMAT, `Field "${field}" must be an object when provided.`, { field });
+    }
+}
+function validateConversation(conversation) {
+    if (!isRecord(conversation)) {
+        throw new GenericHttpPluginError(ERROR_CODES.MISSING_REQUIRED_FIELD, 'Field "conversation" must be an object.', { field: "conversation" });
+    }
+    requireNonEmptyString(conversation.conversationId, "conversation.conversationId");
+    requireNonEmptyString(conversation.type, "conversation.type");
+    if (!CONVERSATION_TYPES.has(conversation.type)) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_FIELD_FORMAT, 'Field "conversation.type" must be one of: dm, group, room, ticket.', { field: "conversation.type" });
+    }
+    validateOptionalString(conversation.title, "conversation.title");
+    validateMetadata(conversation.metadata, "conversation.metadata");
+}
+function validateSender(sender) {
+    if (!isRecord(sender)) {
+        throw new GenericHttpPluginError(ERROR_CODES.MISSING_REQUIRED_FIELD, 'Field "sender" must be an object.', { field: "sender" });
+    }
+    requireNonEmptyString(sender.id, "sender.id");
+    requireNonEmptyString(sender.type, "sender.type");
+    if (!SENDER_TYPES.has(sender.type)) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_FIELD_FORMAT, 'Field "sender.type" must be one of: user, bot, system.', { field: "sender.type" });
+    }
+    validateOptionalString(sender.name, "sender.name");
+    validateMetadata(sender.metadata, "sender.metadata");
+}
+function validateAttachment(attachment, index) {
+    if (!isRecord(attachment)) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_FIELD_FORMAT, `Field "message.attachments[${index}]" must be an object.`, { field: `message.attachments[${index}]` });
+    }
+    if (attachment.kind !== undefined &&
+        (typeof attachment.kind !== "string" ||
+            !ATTACHMENT_KINDS.has(attachment.kind))) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_FIELD_FORMAT, `Field "message.attachments[${index}].kind" must be one of: file, image.`, { field: `message.attachments[${index}].kind` });
+    }
+    validateOptionalString(attachment.id, `message.attachments[${index}].id`);
+    validateOptionalString(attachment.name, `message.attachments[${index}].name`);
+    validateOptionalString(attachment.contentType, `message.attachments[${index}].contentType`);
+    validateOptionalString(attachment.url, `message.attachments[${index}].url`);
+    validateOptionalString(attachment.contentBase64, `message.attachments[${index}].contentBase64`);
+    validateOptionalString(attachment.caption, `message.attachments[${index}].caption`);
+    validateOptionalString(attachment.altText, `message.attachments[${index}].altText`);
+    validateOptionalString(attachment.previewUrl, `message.attachments[${index}].previewUrl`);
+    if (attachment.sizeBytes !== undefined && typeof attachment.sizeBytes !== "number") {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_FIELD_FORMAT, `Field "message.attachments[${index}].sizeBytes" must be a number when provided.`, { field: `message.attachments[${index}].sizeBytes` });
+    }
+    if ((attachment.url === undefined || attachment.url === "") &&
+        (attachment.contentBase64 === undefined || attachment.contentBase64 === "")) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_REQUEST, `Attachment "message.attachments[${index}]" must include either url or contentBase64.`, { field: `message.attachments[${index}]` });
+    }
+    normalizeAttachment(attachment);
+    validateMetadata(attachment.metadata, `message.attachments[${index}].metadata`);
+}
+function validateMessage(message) {
+    if (!isRecord(message)) {
+        throw new GenericHttpPluginError(ERROR_CODES.MISSING_REQUIRED_FIELD, 'Field "message" must be an object.', { field: "message" });
+    }
+    requireNonEmptyString(message.messageId, "message.messageId");
+    validateOptionalString(message.text, "message.text");
+    validateOptionalString(message.replyToMessageId, "message.replyToMessageId");
+    validateMetadata(message.metadata, "message.metadata");
+    if (message.attachments !== undefined) {
+        if (!Array.isArray(message.attachments)) {
+            throw new GenericHttpPluginError(ERROR_CODES.INVALID_FIELD_FORMAT, 'Field "message.attachments" must be an array when provided.', { field: "message.attachments" });
+        }
+        message.attachments.forEach((attachment, index) => validateAttachment(attachment, index));
+    }
+    if ((message.text === undefined || message.text === null || message.text === "") &&
+        (message.attachments === undefined || message.attachments.length === 0)) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_REQUEST, 'Field "message" must include non-empty text or at least one attachment.', { field: "message" });
+    }
+}
+function validateOccurredAt(occurredAt) {
+    validateOptionalString(occurredAt, "occurredAt");
+    if (typeof occurredAt === "string" && Number.isNaN(Date.parse(occurredAt))) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_FIELD_FORMAT, 'Field "occurredAt" must be a valid date-time string.', { field: "occurredAt" });
+    }
+}
+export function validateInboundMessage(request) {
+    if (!isRecord(request)) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_REQUEST, "Inbound message request must be an object.");
+    }
+    requireNonEmptyString(request.eventId, "eventId");
+    requireNonEmptyString(request.accountId, "accountId");
+    validateConversation(request.conversation);
+    validateOptionalString(request.threadId, "threadId");
+    validateSender(request.sender);
+    validateMessage(request.message);
+    validateOccurredAt(request.occurredAt);
+    validateOptionalString(request.idempotencyKey, "idempotencyKey");
+    validateMetadata(request.metadata, "metadata");
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { genericHttpChannelPlugin } from "./channel/plugin.js";
+import { genericHttpHostConfigSchema } from "./config/host-config-schema.js";
+import { openClawGenericHttpPluginEntry } from "./openclaw-entry.js";
+export { createGenericHttpChannelLifecycle } from "./channel/lifecycle.js";
+export type { GenericHttpChannelLifecycle, GenericHttpChannelLifecycleHandlers } from "./channel/lifecycle.js";
+export { createGenericHttpHostAdapter } from "./channel/host-adapter.js";
+export type { GenericHttpHostAdapter, GenericHttpHostAdapterHandlers } from "./channel/host-adapter.js";
+export { createGenericHttpChannelPlugin, genericHttpChannelPlugin } from "./channel/plugin.js";
+export { openClawGenericHttpChannelPlugin, openClawGenericHttpPluginEntry } from "./openclaw-entry.js";
+export type { GenericHttpChannelPlugin, GenericHttpChannelPluginRuntimeOptions, GenericHttpChannelPluginStatus } from "./channel/plugin.js";
+import { type GenericHttpHostAdapter, type GenericHttpHostAdapterHandlers } from "./channel/host-adapter.js";
+import type { GenericHttpPluginConfig } from "./config/schema.js";
+import type { GenericHttpChannelPluginRuntimeOptions } from "./channel/plugin.js";
+export interface GenericHttpPluginChannelDescriptor {
+    name: "generic-http";
+    displayName: "Generic HTTP";
+    configSchemaFile: "./openclaw.config.schema.json";
+}
+export interface GenericHttpPluginRegistration {
+    pluginId: "openclaw-generic-http";
+    channelName: "generic-http";
+    defaultPlugin: typeof genericHttpChannelPlugin;
+    channels: [GenericHttpPluginChannelDescriptor];
+    configSchema: typeof genericHttpHostConfigSchema;
+    createHostAdapter(rawConfig: Partial<GenericHttpPluginConfig>, handlers: GenericHttpHostAdapterHandlers, options?: Omit<GenericHttpChannelPluginRuntimeOptions, "onInboundStreamMessage" | "onInboundStreamError">): GenericHttpHostAdapter;
+}
+export declare function registerPlugin(): GenericHttpPluginRegistration;
+export declare function register(api: {
+    registerChannel: (registration: unknown) => void;
+    registrationMode?: string;
+}): void;
+export declare const activate: typeof register;
+export default openClawGenericHttpPluginEntry;

package/dist/index.js

@@ -0,0 +1,31 @@
+import { genericHttpChannelPlugin } from "./channel/plugin.js";
+import { genericHttpHostConfigSchema } from "./config/host-config-schema.js";
+import { openClawGenericHttpPluginEntry } from "./openclaw-entry.js";
+export { createGenericHttpChannelLifecycle } from "./channel/lifecycle.js";
+export { createGenericHttpHostAdapter } from "./channel/host-adapter.js";
+export { createGenericHttpChannelPlugin, genericHttpChannelPlugin } from "./channel/plugin.js";
+export { openClawGenericHttpChannelPlugin, openClawGenericHttpPluginEntry } from "./openclaw-entry.js";
+import { createGenericHttpHostAdapter } from "./channel/host-adapter.js";
+export function registerPlugin() {
+    return {
+        pluginId: "openclaw-generic-http",
+        channelName: "generic-http",
+        defaultPlugin: genericHttpChannelPlugin,
+        channels: [
+            {
+                name: "generic-http",
+                displayName: "Generic HTTP",
+                configSchemaFile: "./openclaw.config.schema.json"
+            }
+        ],
+        configSchema: genericHttpHostConfigSchema,
+        createHostAdapter(rawConfig, handlers, options) {
+            return createGenericHttpHostAdapter(rawConfig, handlers, options);
+        }
+    };
+}
+export function register(api) {
+    openClawGenericHttpPluginEntry.register(api);
+}
+export const activate = register;
+export default openClawGenericHttpPluginEntry;

package/dist/mapping/conversation-mapper.d.ts

@@ -0,0 +1 @@
+export declare function mapConversationId(conversationId: string): string;

package/dist/mapping/conversation-mapper.js

@@ -0,0 +1,3 @@
+export function mapConversationId(conversationId) {
+    return conversationId.trim();
+}

package/dist/mapping/sender-mapper.d.ts

@@ -0,0 +1 @@
+export declare function mapSenderId(senderId: string): string;

package/dist/mapping/sender-mapper.js

@@ -0,0 +1,3 @@
+export function mapSenderId(senderId) {
+    return senderId.trim();
+}

package/dist/mapping/thread-mapper.d.ts

@@ -0,0 +1 @@
+export declare function mapThreadId(threadId?: string | null): string | null;

package/dist/mapping/thread-mapper.js

@@ -0,0 +1,7 @@
+export function mapThreadId(threadId) {
+    if (typeof threadId !== "string") {
+        return null;
+    }
+    const normalized = threadId.trim();
+    return normalized === "" ? null : normalized;
+}

package/dist/openclaw-entry.d.ts

@@ -0,0 +1,276 @@
+import type { GenericHttpPluginConfig } from "./config/schema.js";
+type OpenClawConfigLike = {
+    channels?: Record<string, unknown>;
+};
+type OpenClawPluginApiLike = {
+    registrationMode?: string;
+    registerChannel: (registration: {
+        plugin: unknown;
+    } | unknown) => void;
+};
+type OpenClawGatewayContextLike = {
+    cfg: OpenClawConfigLike;
+    accountId: string;
+    account: GenericHttpResolvedAccount;
+    abortSignal: AbortSignal;
+    log?: {
+        info?: (message: string) => void;
+        error?: (message: string) => void;
+    };
+    setStatus: (next: Record<string, unknown>) => void;
+    channelRuntime?: unknown;
+};
+type ChannelAccountRuntimeLike = {
+    running?: boolean;
+    connected?: boolean;
+    lastStartAt?: number | null;
+    lastStopAt?: number | null;
+    lastError?: string | null;
+    lastInboundAt?: number | null;
+    lastOutboundAt?: number | null;
+    lastTransportActivityAt?: number | null;
+    probe?: unknown;
+    lastProbeAt?: number | null;
+};
+type GenericHttpResolvedAccount = {
+    accountId: string;
+    enabled: boolean;
+    name?: string;
+    configured: boolean;
+    config: GenericHttpPluginConfig["accounts"][string];
+};
+declare function normalizeTarget(raw: string): string | undefined;
+export declare const openClawGenericHttpChannelPlugin: {
+    id: string;
+    meta: {
+        id: string;
+        label: string;
+        selectionLabel: string;
+        docsPath: string;
+        blurb: string;
+    };
+    capabilities: {
+        chatTypes: string[];
+        media: boolean;
+        threads: boolean;
+    };
+    reload: {
+        configPrefixes: string[];
+    };
+    configSchema: {
+        validate(value: unknown): {
+            ok: boolean;
+            errors: string[];
+            value?: undefined;
+        } | {
+            ok: boolean;
+            value: object;
+            errors?: undefined;
+        };
+    };
+    config: {
+        listAccountIds(cfg: OpenClawConfigLike): string[];
+        resolveAccount(cfg: OpenClawConfigLike, accountId?: string | null): GenericHttpResolvedAccount;
+        defaultAccountId(cfg: OpenClawConfigLike): string;
+        isEnabled(account: GenericHttpResolvedAccount): boolean;
+        isConfigured(account: GenericHttpResolvedAccount): boolean;
+        describeAccount(account: GenericHttpResolvedAccount): {
+            accountId: string;
+            name: string | undefined;
+            enabled: boolean;
+            configured: boolean;
+            baseUrl: string;
+        };
+        setAccountEnabled(params: {
+            cfg: OpenClawConfigLike;
+            accountId: string;
+            enabled: boolean;
+        }): OpenClawConfigLike;
+    };
+    setup: {
+        resolveAccountId(params: {
+            cfg: OpenClawConfigLike;
+            accountId?: string;
+        }): string;
+        validateInput(params: {
+            input: {
+                baseUrl?: string;
+                url?: string;
+                token?: string;
+                secret?: string;
+            };
+        }): "baseUrl is required" | "baseUrl must be a valid absolute URL" | null;
+        applyAccountConfig(params: {
+            cfg: OpenClawConfigLike;
+            accountId: string;
+            input: {
+                baseUrl?: string;
+                url?: string;
+                token?: string;
+                secret?: string;
+            };
+        }): OpenClawConfigLike;
+    };
+    status: {
+        defaultRuntime: {
+            accountId: string;
+            running: boolean;
+            connected: boolean;
+            lastStartAt: null;
+            lastStopAt: null;
+            lastError: null;
+            lastInboundAt: null;
+            lastOutboundAt: null;
+            lastTransportActivityAt: null;
+        };
+        probeAccount(params: {
+            account: GenericHttpResolvedAccount;
+            cfg: OpenClawConfigLike;
+        }): Promise<import("./channel/probe.js").ProbeResult>;
+        buildAccountSnapshot(params: {
+            account: GenericHttpResolvedAccount;
+            runtime?: ChannelAccountRuntimeLike;
+            probe?: {
+                status?: string;
+            };
+        }): {
+            accountId: string;
+            name: string | undefined;
+            enabled: boolean;
+            configured: boolean;
+            baseUrl: string;
+            running: boolean;
+            connected: boolean;
+            lastStartAt: number | null;
+            lastStopAt: number | null;
+            lastError: string | null;
+            lastInboundAt: number | null;
+            lastOutboundAt: number | null;
+            lastTransportActivityAt: number | null;
+            probe: {
+                status?: string;
+            } | undefined;
+            lastProbeAt: number;
+        };
+    };
+    gateway: {
+        startAccount(ctx: OpenClawGatewayContextLike): Promise<void>;
+        stopAccount(ctx: OpenClawGatewayContextLike): Promise<void>;
+    };
+    resolver: {
+        resolveTargets(params: {
+            cfg: OpenClawConfigLike;
+            accountId?: string | null;
+            inputs: string[];
+            kind: "user" | "group";
+        }): Promise<({
+            input: string;
+            resolved: boolean;
+            note: string;
+            id?: undefined;
+            name?: undefined;
+        } | {
+            input: string;
+            resolved: boolean;
+            id: string;
+            name: string;
+            note?: undefined;
+        })[]>;
+    };
+    messaging: {
+        targetPrefixes: string[];
+        normalizeTarget: typeof normalizeTarget;
+        parseExplicitTarget(params: {
+            raw: string;
+        }): {
+            to: string;
+            chatType: "group" | "direct" | "channel";
+        } | null;
+        inferTargetChatType(params: {
+            to: string;
+        }): "group" | "direct" | "channel" | undefined;
+        resolveOutboundSessionRoute(params: {
+            agentId: string;
+            accountId?: string | null;
+            target: string;
+            threadId?: string | number | null;
+        }): {
+            sessionKey: string;
+            baseSessionKey: string;
+            peer: {
+                kind: "group" | "direct" | "channel";
+                id: string;
+            };
+            chatType: "group" | "direct" | "channel";
+            from: string;
+            to: string;
+            threadId: string;
+        } | null;
+        resolveInboundSessionRoute(params: {
+            agentId: string;
+            accountId?: string | null;
+            conversationId: string;
+            conversationType: "dm" | "group" | "room" | "ticket";
+            threadId?: string | number | null;
+        }): {
+            sessionKey: string;
+            baseSessionKey: string;
+            peer: {
+                kind: "group" | "direct" | "channel";
+                id: string;
+            };
+            chatType: "group" | "direct" | "channel";
+            from: string;
+            to: string;
+            threadId: string;
+        } | null;
+    };
+    outbound: {
+        deliveryMode: string;
+        sendText(ctx: {
+            cfg: OpenClawConfigLike;
+            to: string;
+            text: string;
+            threadId?: string | number | null;
+            accountId?: string | null;
+        }): Promise<{
+            channel: string;
+            messageId: string;
+            conversationId: string;
+            timestamp: number;
+            meta: Record<string, unknown>;
+        }>;
+        sendMedia(ctx: {
+            cfg: OpenClawConfigLike;
+            to: string;
+            text: string;
+            mediaUrl?: string;
+            threadId?: string | number | null;
+            accountId?: string | null;
+        }): Promise<{
+            channel: string;
+            messageId: string;
+            conversationId: string;
+            timestamp: number;
+            meta: Record<string, unknown>;
+        }>;
+    };
+};
+export declare const openClawGenericHttpPluginEntry: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        validate(value: unknown): {
+            ok: boolean;
+            value: {};
+            errors?: undefined;
+        } | {
+            ok: boolean;
+            errors: string[];
+            value?: undefined;
+        };
+    };
+    register(api: OpenClawPluginApiLike): void;
+};
+export {};