@kittymi/openclaw-generic-http 0.1.3

package/dist/channel/resolve.d.ts

@@ -0,0 +1,30 @@
+import type { GenericHttpAccountConfig } from "../config/schema.js";
+export interface ResolveRequest {
+    accountId?: string | null;
+    kind: "conversation" | "sender";
+    query: string;
+}
+export interface ResolveResult {
+    id: string;
+    name: string;
+    kind: ResolveRequest["kind"];
+}
+export interface ResolveResponse {
+    success: true;
+    results: ResolveResult[];
+}
+export interface ResolveAccountOptions {
+    fetchImpl?: typeof fetch;
+    nowEpochSeconds?: () => number;
+    nonceFactory?: () => string;
+    requestIdFactory?: () => string;
+}
+/**
+ * Minimal local resolve fallback.
+ *
+ * The first runtime loop has no external lookup client yet, so if callers
+ * already have a stable ID they can pass it through this method and still get a
+ * protocol-shaped resolve response.
+ */
+export declare function resolveLocally(request: ResolveRequest): ResolveResponse;
+export declare function resolveRemotely(accountConfig: GenericHttpAccountConfig, request: ResolveRequest, options?: ResolveAccountOptions): Promise<ResolveResponse>;

package/dist/channel/resolve.js

@@ -0,0 +1,98 @@
+import { randomUUID } from "node:crypto";
+import { serializeProtocolObject } from "../protocol/serializer.js";
+import { signPayload } from "../security/signer.js";
+function buildSignedHeaders(accountConfig, method, path, rawBody, timestamp, nonce, requestId) {
+    const signingSecret = accountConfig.outboundSecret ?? accountConfig.signingSecret ?? "";
+    const signature = signPayload(signingSecret, {
+        method,
+        path,
+        timestamp,
+        nonce,
+        rawBody
+    });
+    return {
+        accept: "application/json",
+        "content-type": "application/json",
+        "x-request-id": requestId,
+        "x-generic-http-version": "1",
+        "x-timestamp": timestamp,
+        "x-nonce": nonce,
+        "x-signature": signature,
+        "x-api-key": accountConfig.apiKey ?? ""
+    };
+}
+/**
+ * Minimal local resolve fallback.
+ *
+ * The first runtime loop has no external lookup client yet, so if callers
+ * already have a stable ID they can pass it through this method and still get a
+ * protocol-shaped resolve response.
+ */
+export function resolveLocally(request) {
+    const query = request.query.trim();
+    if (query === "") {
+        return {
+            success: true,
+            results: []
+        };
+    }
+    return {
+        success: true,
+        results: [
+            {
+                id: query,
+                name: query,
+                kind: request.kind
+            }
+        ]
+    };
+}
+export async function resolveRemotely(accountConfig, request, options = {}) {
+    const query = request.query.trim();
+    if (query === "") {
+        return {
+            success: true,
+            results: []
+        };
+    }
+    const resolvedOptions = {
+        fetchImpl: options.fetchImpl ?? fetch,
+        nowEpochSeconds: options.nowEpochSeconds ?? (() => Math.floor(Date.now() / 1000)),
+        nonceFactory: options.nonceFactory ?? (() => randomUUID()),
+        requestIdFactory: options.requestIdFactory ?? (() => randomUUID())
+    };
+    const endpoint = new URL("/resolve", accountConfig.baseUrl);
+    const rawBody = serializeProtocolObject({
+        accountId: request.accountId ?? undefined,
+        kind: request.kind,
+        query
+    });
+    const timestamp = String(resolvedOptions.nowEpochSeconds());
+    const nonce = resolvedOptions.nonceFactory();
+    const requestId = resolvedOptions.requestIdFactory();
+    const headers = buildSignedHeaders(accountConfig, "POST", endpoint.pathname, rawBody, timestamp, nonce, requestId);
+    const response = await resolvedOptions.fetchImpl(endpoint.toString(), {
+        method: "POST",
+        headers,
+        body: rawBody
+    });
+    if (!response.ok) {
+        throw new Error(`POST /resolve failed with ${response.status} ${response.statusText}`);
+    }
+    const payload = (await response.json());
+    if (payload.success !== true || !Array.isArray(payload.results)) {
+        throw new Error("POST /resolve returned an invalid response payload");
+    }
+    return {
+        success: true,
+        results: payload.results
+            .filter((item) => typeof item.id === "string" &&
+            typeof item.name === "string" &&
+            (item.kind === "conversation" || item.kind === "sender"))
+            .map((item) => ({
+            id: item.id,
+            name: item.name,
+            kind: item.kind
+        }))
+    };
+}

package/dist/channel/stream.d.ts

@@ -0,0 +1,35 @@
+import type { InboundMessageRequestDto } from "../protocol/dto.js";
+import { type NormalizedInboundMessageEvent } from "../inbound/mapper.js";
+import type { GenericHttpAccountConfig } from "../config/schema.js";
+export interface StreamPullOptions {
+    fetchImpl?: typeof fetch;
+    nowEpochSeconds?: () => number;
+    nonceFactory?: () => string;
+    requestIdFactory?: () => string;
+    limit?: number;
+}
+export interface StreamAckOptions {
+    fetchImpl?: typeof fetch;
+    nowEpochSeconds?: () => number;
+    nonceFactory?: () => string;
+    requestIdFactory?: () => string;
+}
+export interface PulledInboundMessage {
+    eventId: string;
+    accountId: string;
+    receivedAt: string;
+    request: InboundMessageRequestDto;
+    normalizedEvent: NormalizedInboundMessageEvent;
+}
+export interface PullInboundMessagesResult {
+    success: true;
+    accountId: string;
+    items: PulledInboundMessage[];
+}
+export interface AckInboundMessagesResult {
+    success: true;
+    accountId: string;
+    ackedEventIds: string[];
+}
+export declare function pullInboundMessages(accountId: string, accountConfig: GenericHttpAccountConfig, options?: StreamPullOptions): Promise<PullInboundMessagesResult>;
+export declare function ackInboundMessages(accountId: string, eventIds: string[], accountConfig: GenericHttpAccountConfig, options?: StreamAckOptions): Promise<AckInboundMessagesResult>;

package/dist/channel/stream.js

@@ -0,0 +1,127 @@
+import { randomUUID } from "node:crypto";
+import { serializeProtocolObject } from "../protocol/serializer.js";
+import { signPayload } from "../security/signer.js";
+import { mapInboundMessage } from "../inbound/mapper.js";
+import { validateInboundMessage } from "../inbound/validator.js";
+function buildSignedHeaders(accountConfig, method, path, rawBody, timestamp, nonce, requestId) {
+    const signingSecret = accountConfig.outboundSecret ?? accountConfig.signingSecret ?? "";
+    const signature = signPayload(signingSecret, {
+        method,
+        path,
+        timestamp,
+        nonce,
+        rawBody
+    });
+    return {
+        accept: "application/json, text/event-stream",
+        "content-type": "application/json",
+        "x-request-id": requestId,
+        "x-generic-http-version": "1",
+        "x-timestamp": timestamp,
+        "x-nonce": nonce,
+        "x-signature": signature,
+        "x-api-key": accountConfig.apiKey ?? ""
+    };
+}
+function resolveRequiredOptions(options) {
+    return {
+        fetchImpl: options.fetchImpl ?? fetch,
+        nowEpochSeconds: options.nowEpochSeconds ?? (() => Math.floor(Date.now() / 1000)),
+        nonceFactory: options.nonceFactory ?? (() => randomUUID()),
+        requestIdFactory: options.requestIdFactory ?? (() => randomUUID())
+    };
+}
+function parseSseEvents(raw) {
+    const chunks = raw
+        .split(/\r?\n\r?\n/)
+        .map((chunk) => chunk.trim())
+        .filter((chunk) => chunk !== "");
+    return chunks.map((chunk) => {
+        const lines = chunk.split(/\r?\n/);
+        let eventName = "message";
+        const dataLines = [];
+        for (const line of lines) {
+            if (line.startsWith("event:")) {
+                eventName = line.slice("event:".length).trim();
+                continue;
+            }
+            if (line.startsWith("data:")) {
+                dataLines.push(line.slice("data:".length).trim());
+            }
+        }
+        return {
+            event: eventName,
+            data: dataLines.join("\n")
+        };
+    });
+}
+export async function pullInboundMessages(accountId, accountConfig, options = {}) {
+    const resolvedOptions = resolveRequiredOptions(options);
+    const endpoint = new URL("/stream/inbound", accountConfig.baseUrl);
+    endpoint.searchParams.set("accountId", accountId);
+    endpoint.searchParams.set("limit", String(options.limit ?? 10));
+    const timestamp = String(resolvedOptions.nowEpochSeconds());
+    const nonce = resolvedOptions.nonceFactory();
+    const requestId = resolvedOptions.requestIdFactory();
+    const headers = buildSignedHeaders(accountConfig, "GET", endpoint.pathname, "", timestamp, nonce, requestId);
+    const response = await resolvedOptions.fetchImpl(endpoint.toString(), {
+        method: "GET",
+        headers
+    });
+    if (!response.ok) {
+        throw new Error(`GET /stream/inbound failed with ${response.status} ${response.statusText}`);
+    }
+    const rawSse = await response.text();
+    const items = parseSseEvents(rawSse)
+        .filter((entry) => entry.event === "inbound-message")
+        .map((entry) => JSON.parse(entry.data))
+        .map((entry) => {
+        validateInboundMessage(entry.request);
+        return {
+            eventId: entry.eventId,
+            accountId: entry.accountId,
+            receivedAt: entry.receivedAt,
+            request: entry.request,
+            normalizedEvent: mapInboundMessage(entry.request)
+        };
+    });
+    return {
+        success: true,
+        accountId,
+        items
+    };
+}
+export async function ackInboundMessages(accountId, eventIds, accountConfig, options = {}) {
+    const normalizedEventIds = eventIds
+        .map((eventId) => eventId.trim())
+        .filter((eventId) => eventId !== "");
+    const resolvedOptions = resolveRequiredOptions(options);
+    const endpoint = new URL("/stream/acks", accountConfig.baseUrl);
+    const rawBody = serializeProtocolObject({
+        accountId,
+        eventIds: normalizedEventIds
+    });
+    const timestamp = String(resolvedOptions.nowEpochSeconds());
+    const nonce = resolvedOptions.nonceFactory();
+    const requestId = resolvedOptions.requestIdFactory();
+    const headers = buildSignedHeaders(accountConfig, "POST", endpoint.pathname, rawBody, timestamp, nonce, requestId);
+    const response = await resolvedOptions.fetchImpl(endpoint.toString(), {
+        method: "POST",
+        headers,
+        body: rawBody
+    });
+    if (!response.ok) {
+        throw new Error(`POST /stream/acks failed with ${response.status} ${response.statusText}`);
+    }
+    const payload = (await response.json());
+    if (payload.success !== true ||
+        payload.accountId !== accountId ||
+        !Array.isArray(payload.ackedEventIds)) {
+        throw new Error("POST /stream/acks returned an invalid response payload");
+    }
+    return {
+        success: true,
+        accountId,
+        ackedEventIds: payload.ackedEventIds.filter((eventId) => typeof eventId === "string")
+    };
+}

package/dist/config/host-config-schema.d.ts

@@ -0,0 +1,21 @@
+export interface GenericHttpHostConfigSchemaProperty {
+    type?: string;
+    title?: string;
+    description?: string;
+    format?: string;
+    minimum?: number;
+    default?: unknown;
+    properties?: Record<string, GenericHttpHostConfigSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean | GenericHttpHostConfigSchemaProperty;
+}
+export interface GenericHttpHostConfigSchema {
+    $schema: string;
+    type: "object";
+    title: string;
+    description: string;
+    properties: Record<string, GenericHttpHostConfigSchemaProperty>;
+    required: string[];
+    additionalProperties: boolean;
+}
+export declare const genericHttpHostConfigSchema: GenericHttpHostConfigSchema;

package/dist/config/host-config-schema.js

@@ -0,0 +1,80 @@
+export const genericHttpHostConfigSchema = {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    type: "object",
+    title: "Generic HTTP Channel Config",
+    description: "Configuration for the OpenClaw generic HTTP channel plugin using bridge/relay webhook and stream ingress.",
+    properties: {
+        enabled: {
+            type: "boolean",
+            title: "Enabled",
+            description: "Whether the generic HTTP channel is enabled.",
+            default: false
+        },
+        defaultAccount: {
+            type: "string",
+            title: "Default Account",
+            description: "Default account ID used when the host does not specify one."
+        },
+        accounts: {
+            type: "object",
+            title: "Accounts",
+            description: "Per-account bridge and outbound transport settings.",
+            additionalProperties: {
+                type: "object",
+                properties: {
+                    baseUrl: {
+                        type: "string",
+                        format: "uri",
+                        title: "Bridge Base URL",
+                        description: "Bridge or relay base URL used for probe, resolve, stream ingress, and outbound delivery."
+                    },
+                    apiKey: {
+                        type: "string",
+                        title: "API Key",
+                        description: "Optional shared credential for bridge authentication."
+                    },
+                    signingSecret: {
+                        type: "string",
+                        title: "Signing Secret",
+                        description: "Shared secret used for signing outbound and stream transport requests."
+                    },
+                    inboundSecret: {
+                        type: "string",
+                        title: "Inbound Secret",
+                        description: "Optional dedicated secret for inbound webhook validation on the bridge side."
+                    },
+                    outboundSecret: {
+                        type: "string",
+                        title: "Outbound Secret",
+                        description: "Optional dedicated secret for outbound signing when outbound trust is split from inbound."
+                    },
+                    connectTimeoutMillis: {
+                        type: "number",
+                        minimum: 0,
+                        title: "Connect Timeout (ms)",
+                        description: "HTTP connect timeout in milliseconds.",
+                        default: 5000
+                    },
+                    readTimeoutMillis: {
+                        type: "number",
+                        minimum: 0,
+                        title: "Read Timeout (ms)",
+                        description: "HTTP read timeout in milliseconds.",
+                        default: 10000
+                    },
+                    maxRetries: {
+                        type: "number",
+                        minimum: 0,
+                        title: "Max Retries",
+                        description: "Maximum retry count for retryable outbound HTTP failures.",
+                        default: 0
+                    }
+                },
+                required: ["baseUrl"],
+                additionalProperties: false
+            }
+        }
+    },
+    required: ["enabled", "defaultAccount", "accounts"],
+    additionalProperties: false
+};

package/dist/config/loader.d.ts

@@ -0,0 +1,7 @@
+import type { GenericHttpPluginConfig } from "./schema.js";
+/**
+ * Normalize partially-hydrated config input into the runtime shape expected by
+ * the plugin. The plugin can then rely on explicit defaults instead of
+ * scattering fallback behavior across transport, validation, and routing code.
+ */
+export declare function loadConfig(rawConfig?: Partial<GenericHttpPluginConfig>): GenericHttpPluginConfig;

package/dist/config/loader.js

@@ -0,0 +1,38 @@
+const DEFAULT_ACCOUNT_ID = "default";
+const DEFAULT_CONNECT_TIMEOUT_MILLIS = 5000;
+const DEFAULT_READ_TIMEOUT_MILLIS = 10000;
+function normalizeAccountConfig(account) {
+    return {
+        baseUrl: account.baseUrl ?? "",
+        apiKey: account.apiKey,
+        signingSecret: account.signingSecret,
+        inboundSecret: account.inboundSecret,
+        outboundSecret: account.outboundSecret,
+        connectTimeoutMillis: account.connectTimeoutMillis ?? DEFAULT_CONNECT_TIMEOUT_MILLIS,
+        readTimeoutMillis: account.readTimeoutMillis ?? DEFAULT_READ_TIMEOUT_MILLIS,
+        maxRetries: account.maxRetries ?? 0
+    };
+}
+/**
+ * Normalize partially-hydrated config input into the runtime shape expected by
+ * the plugin. The plugin can then rely on explicit defaults instead of
+ * scattering fallback behavior across transport, validation, and routing code.
+ */
+export function loadConfig(rawConfig = {}) {
+    const defaultAccount = rawConfig.defaultAccount ?? DEFAULT_ACCOUNT_ID;
+    const rawAccounts = rawConfig.accounts ?? {};
+    const normalizedAccounts = {};
+    Object.entries(rawAccounts).forEach(([accountId, accountConfig]) => {
+        normalizedAccounts[accountId] = normalizeAccountConfig(accountConfig);
+    });
+    // Always materialize the declared default account so downstream routing code
+    // does not need a separate existence fallback.
+    if (normalizedAccounts[defaultAccount] === undefined) {
+        normalizedAccounts[defaultAccount] = normalizeAccountConfig({});
+    }
+    return {
+        enabled: rawConfig.enabled ?? false,
+        defaultAccount,
+        accounts: normalizedAccounts
+    };
+}

package/dist/config/schema.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Per-account runtime configuration for the generic HTTP channel.
+ *
+ * Keep this shape close to the public docs so operators can map config files,
+ * CLI setup, and runtime behavior without translating between models.
+ */
+export interface GenericHttpAccountConfig {
+    /**
+     * Base URL of the third-party bridge service that receives outbound calls
+     * and exposes health/probe endpoints.
+     */
+    baseUrl: string;
+    /**
+     * Shared API credential used for basic transport authentication.
+     */
+    apiKey?: string;
+    /**
+     * Shared secret used to sign outbound requests and verify inbound requests.
+     */
+    signingSecret?: string;
+    /**
+     * Optional dedicated secret for inbound validation when callers should not
+     * share the same secret used for outbound plugin requests.
+     */
+    inboundSecret?: string;
+    /**
+     * Optional dedicated secret for outbound signing when rotation or separation
+     * of trust domains is required.
+     */
+    outboundSecret?: string;
+    /**
+     * Connection timeout for outbound HTTP calls, in milliseconds.
+     */
+    connectTimeoutMillis?: number;
+    /**
+     * Read timeout for outbound HTTP calls, in milliseconds.
+     */
+    readTimeoutMillis?: number;
+    /**
+     * Maximum retry attempts for retryable outbound transport failures.
+     */
+    maxRetries?: number;
+}
+export interface GenericHttpPluginConfig {
+    enabled: boolean;
+    defaultAccount: string;
+    accounts: Record<string, GenericHttpAccountConfig>;
+}

package/dist/config/schema.js

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

package/dist/errors/codes.d.ts

@@ -0,0 +1,11 @@
+export declare const ERROR_CODES: {
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    readonly MISSING_REQUIRED_FIELD: "MISSING_REQUIRED_FIELD";
+    readonly INVALID_FIELD_FORMAT: "INVALID_FIELD_FORMAT";
+    readonly INVALID_CREDENTIAL: "INVALID_CREDENTIAL";
+    readonly INVALID_SIGNATURE: "INVALID_SIGNATURE";
+    readonly TIMESTAMP_EXPIRED: "TIMESTAMP_EXPIRED";
+    readonly NONCE_REPLAYED: "NONCE_REPLAYED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];

package/dist/errors/codes.js

@@ -0,0 +1,10 @@
+export const ERROR_CODES = {
+    INVALID_REQUEST: "INVALID_REQUEST",
+    MISSING_REQUIRED_FIELD: "MISSING_REQUIRED_FIELD",
+    INVALID_FIELD_FORMAT: "INVALID_FIELD_FORMAT",
+    INVALID_CREDENTIAL: "INVALID_CREDENTIAL",
+    INVALID_SIGNATURE: "INVALID_SIGNATURE",
+    TIMESTAMP_EXPIRED: "TIMESTAMP_EXPIRED",
+    NONCE_REPLAYED: "NONCE_REPLAYED",
+    INTERNAL_ERROR: "INTERNAL_ERROR"
+};

package/dist/errors/exceptions.d.ts

@@ -0,0 +1,7 @@
+import type { ErrorCode } from "./codes.js";
+export declare class GenericHttpPluginError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly retryable: boolean;
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown>, retryable?: boolean);
+}

package/dist/errors/exceptions.js

@@ -0,0 +1,12 @@
+export class GenericHttpPluginError extends Error {
+    code;
+    details;
+    retryable;
+    constructor(code, message, details, retryable = false) {
+        super(message);
+        this.name = "GenericHttpPluginError";
+        this.code = code;
+        this.details = details;
+        this.retryable = retryable;
+    }
+}

package/dist/inbound/mapper.d.ts

@@ -0,0 +1,21 @@
+import type { AttachmentDto, InboundMessageRequestDto } from "../protocol/dto.js";
+export interface NormalizedInboundMessageEvent {
+    eventId: string;
+    eventType: "message.created";
+    accountId: string;
+    conversationId: string;
+    conversationType: string;
+    conversationTitle: string | null;
+    threadId: string | null;
+    senderId: string;
+    senderName: string | null;
+    senderType: string;
+    messageId: string;
+    text: string | null;
+    attachments: AttachmentDto[];
+    replyToMessageId: string | null;
+    occurredAt: string | null;
+    idempotencyKey: string | null;
+    metadata: Record<string, unknown>;
+}
+export declare function mapInboundMessage(request: InboundMessageRequestDto): NormalizedInboundMessageEvent;

package/dist/inbound/mapper.js

@@ -0,0 +1,22 @@
+export function mapInboundMessage(request) {
+    return {
+        eventId: request.eventId,
+        eventType: "message.created",
+        accountId: request.accountId,
+        conversationId: request.conversation.conversationId,
+        conversationType: request.conversation.type,
+        conversationTitle: request.conversation.title ?? null,
+        threadId: request.threadId ?? null,
+        senderId: request.sender.id,
+        senderName: request.sender.name ?? null,
+        senderType: request.sender.type,
+        messageId: request.message.messageId,
+        text: request.message.text ?? null,
+        attachments: request.message.attachments ?? [],
+        replyToMessageId: request.message.replyToMessageId ?? null,
+        occurredAt: request.occurredAt ?? null,
+        idempotencyKey: request.idempotencyKey ?? null,
+        // Keep metadata object-shaped for downstream handlers even when omitted.
+        metadata: request.metadata ?? {}
+    };
+}

package/dist/inbound/validator.d.ts

@@ -0,0 +1,4 @@
+import type { InboundMessageRequestDto } from "../protocol/dto.js";
+type InboundMessageRequest = InboundMessageRequestDto;
+export declare function validateInboundMessage(request: InboundMessageRequest): asserts request is InboundMessageRequestDto;
+export {};