@kittymi/openclaw-generic-http 0.1.3

package/dist/outbound/client.d.ts

@@ -0,0 +1,6 @@
+import type { OutboundMessageRequest, OutboundMessageResult } from "./mapper.js";
+export interface OutboundClient {
+    send(request: OutboundMessageRequest): Promise<OutboundMessageResult>;
+}
+export { HttpOutboundClient } from "./http-client.js";
+export type { HttpOutboundClientOptions } from "./http-client.js";

package/dist/outbound/client.js

@@ -0,0 +1 @@
+export { HttpOutboundClient } from "./http-client.js";

package/dist/outbound/controller.d.ts

@@ -0,0 +1,15 @@
+import type { OutboundClient } from "./client.js";
+import { type InternalOutboundMessage, type OutboundMessageResult } from "./mapper.js";
+export interface OutboundHandlingSuccess {
+    result: OutboundMessageResult;
+}
+export interface OutboundHandlingError {
+    success: false;
+    code: string;
+    message: string;
+    requestId: string;
+    details?: Record<string, unknown>;
+    retryable: boolean;
+}
+export declare function buildOutboundErrorResponse(requestId: string, error: unknown): OutboundHandlingError;
+export declare function handleOutboundMessage(client: OutboundClient, message: InternalOutboundMessage): Promise<OutboundHandlingSuccess>;

package/dist/outbound/controller.js

@@ -0,0 +1,28 @@
+import { GenericHttpPluginError } from "../errors/exceptions.js";
+import { sendOutboundMessage } from "./sender.js";
+export function buildOutboundErrorResponse(requestId, error) {
+    if (error instanceof GenericHttpPluginError) {
+        return {
+            success: false,
+            code: error.code,
+            message: error.message,
+            requestId,
+            details: error.details,
+            retryable: error.retryable
+        };
+    }
+    return {
+        success: false,
+        code: "INTERNAL_ERROR",
+        message: "Unexpected outbound message handling failure.",
+        requestId,
+        retryable: true
+    };
+}
+export async function handleOutboundMessage(client, message) {
+    // The outbound control path mirrors inbound: normalize the internal message,
+    // delegate delivery to the transport client, and return a protocol-shaped
+    // result for the caller or HTTP layer.
+    const result = await sendOutboundMessage(client, message);
+    return { result };
+}

package/dist/outbound/http-client.d.ts

@@ -0,0 +1,23 @@
+import type { GenericHttpAccountConfig } from "../config/schema.js";
+import type { OutboundClient } from "./client.js";
+import type { OutboundMessageRequest, OutboundMessageResult } from "./mapper.js";
+export interface HttpOutboundClientOptions {
+    nowEpochSeconds?: () => number;
+    nonceFactory?: () => string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Minimal HTTP transport for the generic bridge outbound path.
+ *
+ * The caller hands over a normalized outbound request, this client signs the
+ * serialized body with the account secret, and then posts it to the configured
+ * third-party bridge endpoint.
+ */
+export declare class HttpOutboundClient implements OutboundClient {
+    private readonly accountConfig;
+    private readonly nowEpochSeconds;
+    private readonly nonceFactory;
+    private readonly fetchImpl;
+    constructor(accountConfig: GenericHttpAccountConfig, options?: HttpOutboundClientOptions);
+    send(request: OutboundMessageRequest): Promise<OutboundMessageResult>;
+}

package/dist/outbound/http-client.js

@@ -0,0 +1,150 @@
+import { ERROR_CODES } from "../errors/codes.js";
+import { GenericHttpPluginError } from "../errors/exceptions.js";
+import { normalizeAttachment } from "../protocol/attachments.js";
+import { serializeProtocolObject } from "../protocol/serializer.js";
+import { signPayload } from "../security/signer.js";
+function normalizeOutboundRequest(request) {
+    return {
+        ...request,
+        message: {
+            ...request.message,
+            attachments: (request.message.attachments ?? []).map((attachment) => normalizeAttachment(attachment))
+        }
+    };
+}
+function createTimeoutSignal(timeoutMillis) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMillis);
+    controller.signal.addEventListener("abort", () => clearTimeout(timer), {
+        once: true
+    });
+    return controller.signal;
+}
+function buildOutboundEndpoint(baseUrl) {
+    if (baseUrl.trim() === "") {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_REQUEST, "Outbound account config requires a non-empty baseUrl.", { field: "baseUrl" });
+    }
+    return new URL("/outbound/messages", baseUrl).toString();
+}
+function buildOutboundHeaders(accountConfig, request, signature, timestamp, nonce) {
+    return {
+        accept: "application/json",
+        "content-type": "application/json",
+        "x-api-key": accountConfig.apiKey ?? "",
+        "x-generic-http-version": "1",
+        "x-nonce": nonce,
+        "x-request-id": request.requestId,
+        "x-signature": signature,
+        "x-timestamp": timestamp
+    };
+}
+function parseOutboundResult(value) {
+    if (typeof value !== "object" || value === null) {
+        throw new GenericHttpPluginError(ERROR_CODES.INTERNAL_ERROR, "Outbound endpoint returned a non-object response.", { responseType: typeof value });
+    }
+    const result = value;
+    if (result.success !== true ||
+        result.code !== "DELIVERED" ||
+        typeof result.providerMessageId !== "string" ||
+        typeof result.acceptedAt !== "string") {
+        throw new GenericHttpPluginError(ERROR_CODES.INTERNAL_ERROR, "Outbound endpoint returned an invalid delivery result.", {
+            response: value
+        });
+    }
+    return {
+        success: true,
+        code: "DELIVERED",
+        providerMessageId: result.providerMessageId,
+        acceptedAt: result.acceptedAt,
+        metadata: typeof result.metadata === "object" && result.metadata !== null
+            ? result.metadata
+            : {}
+    };
+}
+function isRetryableStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+function shouldRetry(error) {
+    if (error instanceof GenericHttpPluginError) {
+        return error.retryable;
+    }
+    if (error instanceof Error) {
+        return error.name === "AbortError" || error.name === "TypeError";
+    }
+    return false;
+}
+function createTransportError(code, message, details, retryable = false) {
+    return new GenericHttpPluginError(code, message, details, retryable);
+}
+/**
+ * Minimal HTTP transport for the generic bridge outbound path.
+ *
+ * The caller hands over a normalized outbound request, this client signs the
+ * serialized body with the account secret, and then posts it to the configured
+ * third-party bridge endpoint.
+ */
+export class HttpOutboundClient {
+    accountConfig;
+    nowEpochSeconds;
+    nonceFactory;
+    fetchImpl;
+    constructor(accountConfig, options = {}) {
+        this.accountConfig = accountConfig;
+        this.nowEpochSeconds =
+            options.nowEpochSeconds ?? (() => Math.floor(Date.now() / 1000));
+        this.nonceFactory = options.nonceFactory ?? (() => crypto.randomUUID());
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async send(request) {
+        const endpoint = buildOutboundEndpoint(this.accountConfig.baseUrl);
+        const normalizedRequest = normalizeOutboundRequest(request);
+        const rawBody = serializeProtocolObject(normalizedRequest);
+        const timestamp = String(this.nowEpochSeconds());
+        const nonce = this.nonceFactory();
+        const signingSecret = this.accountConfig.outboundSecret ?? this.accountConfig.signingSecret;
+        if (signingSecret === undefined || signingSecret.trim() === "") {
+            throw new GenericHttpPluginError(ERROR_CODES.INVALID_REQUEST, "Outbound account config requires signingSecret or outboundSecret.", {
+                accountId: request.accountId
+            });
+        }
+        const path = new URL(endpoint).pathname;
+        const signature = signPayload(signingSecret, {
+            method: "POST",
+            path,
+            timestamp,
+            nonce,
+            rawBody
+        });
+        const maxAttempts = Math.max(1, (this.accountConfig.maxRetries ?? 0) + 1);
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            try {
+                const response = await this.fetchImpl(endpoint, {
+                    method: "POST",
+                    headers: buildOutboundHeaders(this.accountConfig, normalizedRequest, signature, timestamp, nonce),
+                    body: rawBody,
+                    signal: createTimeoutSignal(this.accountConfig.readTimeoutMillis ?? 10000)
+                });
+                if (!response.ok) {
+                    throw createTransportError(ERROR_CODES.INTERNAL_ERROR, `Outbound HTTP request failed with status ${response.status} ${response.statusText}.`, {
+                        status: response.status,
+                        statusText: response.statusText
+                    }, isRetryableStatus(response.status));
+                }
+                return parseOutboundResult(await response.json());
+            }
+            catch (error) {
+                if (attempt >= maxAttempts || !shouldRetry(error)) {
+                    if (error instanceof GenericHttpPluginError) {
+                        throw error;
+                    }
+                    throw createTransportError(ERROR_CODES.INTERNAL_ERROR, "Outbound HTTP transport failed before a valid delivery result was received.", {
+                        cause: error instanceof Error
+                            ? `${error.name}: ${error.message}`
+                            : String(error)
+                    }, true);
+                }
+            }
+        }
+        throw createTransportError(ERROR_CODES.INTERNAL_ERROR, "Outbound HTTP transport exhausted retries without returning a delivery result.", { accountId: request.accountId }, true);
+    }
+}

package/dist/outbound/mapper.d.ts

@@ -0,0 +1,29 @@
+import type { AttachmentDto, ConversationDto, MessageDto } from "../protocol/dto.js";
+export interface OutboundMessageRequest {
+    requestId: string;
+    accountId: string;
+    conversation: ConversationDto;
+    threadId: string | null;
+    message: MessageDto;
+    metadata: Record<string, unknown>;
+}
+export interface OutboundMessageResult {
+    success: true;
+    code: "DELIVERED";
+    providerMessageId: string;
+    acceptedAt: string;
+    metadata: Record<string, unknown>;
+}
+export interface InternalOutboundMessage {
+    requestId: string;
+    accountId: string;
+    conversationId: string;
+    conversationType: ConversationDto["type"];
+    threadId?: string | null;
+    messageId: string;
+    text?: string | null;
+    attachments?: AttachmentDto[];
+    replyToMessageId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export declare function mapOutboundMessage(message: InternalOutboundMessage): OutboundMessageRequest;

package/dist/outbound/mapper.js

@@ -0,0 +1,19 @@
+import { normalizeAttachment } from "../protocol/attachments.js";
+export function mapOutboundMessage(message) {
+    return {
+        requestId: message.requestId,
+        accountId: message.accountId,
+        conversation: {
+            conversationId: message.conversationId,
+            type: message.conversationType
+        },
+        threadId: message.threadId ?? null,
+        message: {
+            messageId: message.messageId,
+            text: message.text ?? null,
+            attachments: (message.attachments ?? []).map((attachment) => normalizeAttachment(attachment)),
+            replyToMessageId: message.replyToMessageId ?? null
+        },
+        metadata: message.metadata ?? {}
+    };
+}

package/dist/outbound/mock-client.d.ts

@@ -0,0 +1,18 @@
+import type { OutboundClient } from "./client.js";
+import type { OutboundMessageRequest, OutboundMessageResult } from "./mapper.js";
+export interface MockOutboundClientOptions {
+    nowIsoString?: () => string;
+    providerMessageIdPrefix?: string;
+}
+/**
+ * Simple in-memory outbound client for local demos and tests. It lets the
+ * plugin exercise the full outbound mapping/sender/controller flow before a
+ * real HTTP transport is introduced.
+ */
+export declare class MockOutboundClient implements OutboundClient {
+    readonly requests: OutboundMessageRequest[];
+    private readonly nowIsoString;
+    private readonly providerMessageIdPrefix;
+    constructor(options?: MockOutboundClientOptions);
+    send(request: OutboundMessageRequest): Promise<OutboundMessageResult>;
+}

package/dist/outbound/mock-client.js

@@ -0,0 +1,26 @@
+/**
+ * Simple in-memory outbound client for local demos and tests. It lets the
+ * plugin exercise the full outbound mapping/sender/controller flow before a
+ * real HTTP transport is introduced.
+ */
+export class MockOutboundClient {
+    requests = [];
+    nowIsoString;
+    providerMessageIdPrefix;
+    constructor(options = {}) {
+        this.nowIsoString = options.nowIsoString ?? (() => new Date().toISOString());
+        this.providerMessageIdPrefix = options.providerMessageIdPrefix ?? "mock";
+    }
+    async send(request) {
+        this.requests.push(request);
+        return {
+            success: true,
+            code: "DELIVERED",
+            providerMessageId: `${this.providerMessageIdPrefix}-${request.message.messageId}`,
+            acceptedAt: this.nowIsoString(),
+            metadata: {
+                transport: "mock"
+            }
+        };
+    }
+}

package/dist/outbound/sender.d.ts

@@ -0,0 +1,3 @@
+import type { OutboundClient } from "./client.js";
+import { type InternalOutboundMessage, type OutboundMessageResult } from "./mapper.js";
+export declare function sendOutboundMessage(client: OutboundClient, message: InternalOutboundMessage): Promise<OutboundMessageResult>;

package/dist/outbound/sender.js

@@ -0,0 +1,5 @@
+import { mapOutboundMessage } from "./mapper.js";
+export async function sendOutboundMessage(client, message) {
+    const request = mapOutboundMessage(message);
+    return client.send(request);
+}

package/dist/protocol/attachments.d.ts

@@ -0,0 +1,10 @@
+import type { AttachmentDto } from "./dto.js";
+export declare const DEFAULT_MAX_ATTACHMENT_SIZE_BYTES: number;
+export interface NormalizeAttachmentOptions {
+    maxAttachmentSizeBytes?: number;
+}
+/**
+ * Centralize attachment shaping rules so inbound validation and outbound
+ * serialization do not drift apart when file/image support evolves.
+ */
+export declare function normalizeAttachment(attachment: AttachmentDto, options?: NormalizeAttachmentOptions): AttachmentDto;

package/dist/protocol/attachments.js

@@ -0,0 +1,56 @@
+import { ERROR_CODES } from "../errors/codes.js";
+import { GenericHttpPluginError } from "../errors/exceptions.js";
+export const DEFAULT_MAX_ATTACHMENT_SIZE_BYTES = 25 * 1024 * 1024;
+function inferAttachmentKind(attachment) {
+    if (attachment.kind !== undefined) {
+        return attachment.kind;
+    }
+    if (attachment.contentType?.startsWith("image/") === true) {
+        return "image";
+    }
+    return "file";
+}
+function normalizeAttachmentName(attachment) {
+    if (attachment.name === undefined) {
+        return undefined;
+    }
+    const normalized = attachment.name.trim();
+    return normalized === "" ? undefined : normalized;
+}
+/**
+ * Centralize attachment shaping rules so inbound validation and outbound
+ * serialization do not drift apart when file/image support evolves.
+ */
+export function normalizeAttachment(attachment, options = {}) {
+    const normalized = {
+        kind: inferAttachmentKind(attachment),
+        id: attachment.id,
+        name: normalizeAttachmentName(attachment),
+        contentType: attachment.contentType,
+        url: attachment.url,
+        contentBase64: attachment.contentBase64,
+        sizeBytes: attachment.sizeBytes,
+        caption: attachment.caption ?? null,
+        altText: attachment.altText ?? null,
+        previewUrl: attachment.previewUrl,
+        metadata: attachment.metadata ?? {}
+    };
+    const maxAttachmentSizeBytes = options.maxAttachmentSizeBytes ?? DEFAULT_MAX_ATTACHMENT_SIZE_BYTES;
+    if (normalized.sizeBytes !== undefined &&
+        normalized.sizeBytes > maxAttachmentSizeBytes) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_REQUEST, "Attachment size exceeds the supported maximum.", {
+            maxAttachmentSizeBytes,
+            sizeBytes: normalized.sizeBytes
+        });
+    }
+    if (normalized.kind === "image") {
+        if (normalized.contentType !== undefined &&
+            !normalized.contentType.startsWith("image/")) {
+            throw new GenericHttpPluginError(ERROR_CODES.INVALID_FIELD_FORMAT, "Image attachment contentType must start with image/.", {
+                field: "contentType",
+                contentType: normalized.contentType
+            });
+        }
+    }
+    return normalized;
+}

package/dist/protocol/dto.d.ts

@@ -0,0 +1,46 @@
+export interface ConversationDto {
+    conversationId: string;
+    type: ConversationType;
+    title?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export type ConversationType = "dm" | "group" | "room" | "ticket";
+export type SenderType = "user" | "bot" | "system";
+export type AttachmentKind = "file" | "image";
+export interface SenderDto {
+    id: string;
+    name?: string | null;
+    type: SenderType;
+    metadata?: Record<string, unknown>;
+}
+export interface AttachmentDto {
+    kind?: AttachmentKind;
+    id?: string;
+    name?: string;
+    contentType?: string;
+    url?: string;
+    contentBase64?: string;
+    sizeBytes?: number;
+    caption?: string | null;
+    altText?: string | null;
+    previewUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface MessageDto {
+    messageId: string;
+    text?: string | null;
+    attachments?: AttachmentDto[];
+    replyToMessageId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface InboundMessageRequestDto {
+    eventId: string;
+    accountId: string;
+    conversation: ConversationDto;
+    threadId?: string | null;
+    sender: SenderDto;
+    message: MessageDto;
+    occurredAt?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+}

package/dist/protocol/dto.js

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

package/dist/protocol/serializer.d.ts

@@ -0,0 +1 @@
+export declare function serializeProtocolObject(value: unknown): string;

package/dist/protocol/serializer.js

@@ -0,0 +1,3 @@
+export function serializeProtocolObject(value) {
+    return JSON.stringify(value);
+}

package/dist/security/nonce-store.d.ts

@@ -0,0 +1,30 @@
+export interface NonceStore {
+    tryUse(nonce: string, timestampEpochSeconds: number): boolean;
+}
+export interface InMemoryNonceStoreOptions {
+    /**
+     * Maximum allowed age window for accepted nonces, in seconds.
+     *
+     * Entries older than this window are evicted during normal insert/check
+     * operations so the store stays bounded for the minimum viable runtime.
+     */
+    ttlSeconds?: number;
+    /**
+     * Clock source override for tests and deterministic validation flows.
+     */
+    nowEpochSeconds?: () => number;
+}
+/**
+ * Small in-memory nonce store for local development and single-process
+ * deployments. This is enough for the first runtime loop and can later be
+ * replaced with Redis or another shared backing store without changing the
+ * caller contract.
+ */
+export declare class InMemoryNonceStore implements NonceStore {
+    private readonly ttlSeconds;
+    private readonly nowEpochSeconds;
+    private readonly entries;
+    constructor(options?: InMemoryNonceStoreOptions);
+    tryUse(nonce: string, timestampEpochSeconds: number): boolean;
+    private evictExpired;
+}

package/dist/security/nonce-store.js

@@ -0,0 +1,32 @@
+const DEFAULT_TTL_SECONDS = 300;
+/**
+ * Small in-memory nonce store for local development and single-process
+ * deployments. This is enough for the first runtime loop and can later be
+ * replaced with Redis or another shared backing store without changing the
+ * caller contract.
+ */
+export class InMemoryNonceStore {
+    ttlSeconds;
+    nowEpochSeconds;
+    entries = new Map();
+    constructor(options = {}) {
+        this.ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+        this.nowEpochSeconds = options.nowEpochSeconds ?? (() => Math.floor(Date.now() / 1000));
+    }
+    tryUse(nonce, timestampEpochSeconds) {
+        this.evictExpired();
+        if (this.entries.has(nonce)) {
+            return false;
+        }
+        this.entries.set(nonce, timestampEpochSeconds);
+        return true;
+    }
+    evictExpired() {
+        const cutoff = this.nowEpochSeconds() - this.ttlSeconds;
+        for (const [nonce, timestamp] of this.entries.entries()) {
+            if (timestamp < cutoff) {
+                this.entries.delete(nonce);
+            }
+        }
+    }
+}

package/dist/security/signer.d.ts

@@ -0,0 +1,10 @@
+export interface SignatureInput {
+    method: string;
+    path: string;
+    timestamp: string;
+    nonce: string;
+    rawBody?: string | null;
+}
+export declare function sha256Hex(rawBody?: string | null): string;
+export declare function buildCanonicalString(input: SignatureInput): string;
+export declare function signPayload(secret: string, input: SignatureInput): string;

package/dist/security/signer.js

@@ -0,0 +1,20 @@
+import { createHash, createHmac } from "node:crypto";
+export function sha256Hex(rawBody) {
+    return createHash("sha256").update(rawBody ?? "", "utf8").digest("hex");
+}
+export function buildCanonicalString(input) {
+    // Keep canonicalization byte-for-byte aligned with the published protocol spec
+    // so every SDK and plugin implementation produces the same signature.
+    return [
+        input.method.toUpperCase(),
+        input.path,
+        input.timestamp,
+        input.nonce,
+        sha256Hex(input.rawBody)
+    ].join("\n");
+}
+export function signPayload(secret, input) {
+    return createHmac("sha256", secret)
+        .update(buildCanonicalString(input), "utf8")
+        .digest("hex");
+}

package/dist/security/verifier.d.ts

@@ -0,0 +1,2 @@
+import { type SignatureInput } from "./signer.js";
+export declare function verifyPayload(expectedSignature: string, secret: string, input: SignatureInput): boolean;

package/dist/security/verifier.js

@@ -0,0 +1,20 @@
+import { timingSafeEqual } from "node:crypto";
+import { signPayload } from "./signer.js";
+function normalizeHex(value) {
+    if (!/^[0-9a-f]+$/i.test(value) || value.length % 2 !== 0) {
+        return null;
+    }
+    return Buffer.from(value.toLowerCase(), "hex");
+}
+export function verifyPayload(expectedSignature, secret, input) {
+    const provided = normalizeHex(expectedSignature);
+    if (provided === null) {
+        return false;
+    }
+    const computed = normalizeHex(signPayload(secret, input));
+    if (computed === null || provided.length !== computed.length) {
+        return false;
+    }
+    // Avoid leaking signature match information through early-return timing.
+    return timingSafeEqual(provided, computed);
+}