openclaw-seatalk 0.1.0

package/src/relay-client.ts

@@ -0,0 +1,204 @@
+import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk";
+import WebSocket from "ws";
+import { listEnabledSeaTalkAccounts, resolveSeaTalkAccount } from "./accounts.js";
+import { dispatchSeaTalkEvent } from "./bot.js";
+import { resolveSeaTalkClient } from "./client.js";
+import type { MonitorSeaTalkOpts } from "./monitor.js";
+import type { ResolvedSeaTalkAccount, SeaTalkCallbackRequest } from "./types.js";
+
+const INITIAL_BACKOFF_MS = 1_000;
+const MAX_BACKOFF_MS = 30_000;
+const BACKOFF_MULTIPLIER = 2;
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+async function connectSingleAccount(params: {
+	cfg: ClawdbotConfig;
+	account: ResolvedSeaTalkAccount;
+	relayUrl: string;
+	runtime?: RuntimeEnv;
+	abortSignal?: AbortSignal;
+}): Promise<void> {
+	const { cfg, account, relayUrl, runtime, abortSignal } = params;
+	const { accountId } = account;
+	const log = runtime?.log ?? console.log;
+	const error = runtime?.error ?? console.error;
+
+	if (!account.appId || !account.appSecret || !account.signingSecret) {
+		throw new Error(`SeaTalk account "${accountId}" missing credentials for relay mode`);
+	}
+
+	const client = resolveSeaTalkClient(account);
+	if (!client) {
+		throw new Error(`SeaTalk client not available for account "${accountId}"`);
+	}
+
+	let backoff = INITIAL_BACKOFF_MS;
+
+	while (!abortSignal?.aborted) {
+		try {
+			await new Promise<void>((resolve, reject) => {
+				if (abortSignal?.aborted) {
+					resolve();
+					return;
+				}
+
+				log(`seatalk[${accountId}]: connecting to relay ${relayUrl}...`);
+				const ws = new WebSocket(relayUrl);
+
+				const handleAbort = () => {
+					ws.close();
+					resolve();
+				};
+				abortSignal?.addEventListener("abort", handleAbort, { once: true });
+
+				ws.on("open", () => {
+					log(`seatalk[${accountId}]: relay connected, authenticating...`);
+					ws.send(
+						JSON.stringify({
+							type: "auth",
+							appId: account.appId,
+							appSecret: account.appSecret,
+							signingSecret: account.signingSecret,
+						}),
+					);
+				});
+
+				let authenticated = false;
+
+				ws.on("message", (raw) => {
+					let msg: { type: string; event?: SeaTalkCallbackRequest; error?: string };
+					try {
+						msg = JSON.parse(String(raw));
+					} catch {
+						error(`seatalk[${accountId}]: relay sent invalid JSON`);
+						return;
+					}
+
+					if (!authenticated) {
+						if (msg.type === "auth_ok") {
+							authenticated = true;
+							backoff = INITIAL_BACKOFF_MS;
+							log(`seatalk[${accountId}]: relay authenticated`);
+						} else if (msg.type === "auth_fail") {
+							error(`seatalk[${accountId}]: relay auth failed: ${msg.error}`);
+							ws.close();
+							reject(new Error(`Relay auth failed: ${msg.error}`));
+						}
+						return;
+					}
+
+					switch (msg.type) {
+						case "event":
+							if (msg.event && client) {
+								dispatchSeaTalkEvent({
+									cfg,
+									event: msg.event,
+									client,
+									runtime,
+									accountId,
+								});
+							}
+							break;
+						case "ping":
+							ws.send(JSON.stringify({ type: "pong" }));
+							break;
+						case "replaced":
+							log(`seatalk[${accountId}]: connection replaced by another instance`);
+							ws.close();
+							resolve();
+							return;
+						default:
+							log(`seatalk[${accountId}]: unknown relay message type: ${msg.type}`);
+					}
+				});
+
+				ws.on("close", (code, reason) => {
+					abortSignal?.removeEventListener("abort", handleAbort);
+					if (authenticated) {
+						log(
+							`seatalk[${accountId}]: relay disconnected (code=${code}, reason=${String(reason)})`,
+						);
+					}
+					resolve();
+				});
+
+				ws.on("error", (err) => {
+					abortSignal?.removeEventListener("abort", handleAbort);
+					error(`seatalk[${accountId}]: relay connection error: ${String(err)}`);
+					resolve();
+				});
+			});
+		} catch (err) {
+			const msg = String(err);
+			if (msg.includes("Relay auth failed")) {
+				throw err;
+			}
+			error(`seatalk[${accountId}]: relay error: ${msg}`);
+		}
+
+		if (abortSignal?.aborted) break;
+
+		log(`seatalk[${accountId}]: reconnecting in ${backoff}ms...`);
+		await sleep(backoff, abortSignal);
+		backoff = Math.min(backoff * BACKOFF_MULTIPLIER, MAX_BACKOFF_MS);
+	}
+}
+
+export async function connectSeaTalkRelay(
+	opts: MonitorSeaTalkOpts & { relayUrl: string },
+): Promise<void> {
+	const cfg = opts.config;
+	if (!cfg) {
+		throw new Error("Config is required for SeaTalk relay client");
+	}
+
+	const log = opts.runtime?.log ?? console.log;
+
+	if (opts.accountId) {
+		const account = resolveSeaTalkAccount({ cfg, accountId: opts.accountId });
+		if (!account.enabled || !account.configured) {
+			throw new Error(`SeaTalk account "${opts.accountId}" not configured or disabled`);
+		}
+		return connectSingleAccount({
+			cfg,
+			account,
+			relayUrl: opts.relayUrl,
+			runtime: opts.runtime,
+			abortSignal: opts.abortSignal,
+		});
+	}
+
+	const accounts = listEnabledSeaTalkAccounts(cfg);
+	if (accounts.length === 0) {
+		throw new Error("No enabled SeaTalk accounts configured");
+	}
+
+	log(
+		`seatalk: connecting ${accounts.length} account(s) to relay: ${accounts.map((a) => a.accountId).join(", ")}`,
+	);
+
+	await Promise.all(
+		accounts.map((account) =>
+			connectSingleAccount({
+				cfg,
+				account,
+				relayUrl: opts.relayUrl,
+				runtime: opts.runtime,
+				abortSignal: opts.abortSignal,
+			}),
+		),
+	);
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setSeatalkRuntime(next: PluginRuntime) {
+	runtime = next;
+}
+
+export function getSeatalkRuntime(): PluginRuntime {
+	if (!runtime) {
+		throw new Error("SeaTalk runtime not initialized");
+	}
+	return runtime;
+}

package/src/send.ts

@@ -0,0 +1,71 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { resolveSeaTalkAccount } from "./accounts.js";
+import { type SeaTalkClient, resolveSeaTalkClient } from "./client.js";
+
+export async function sendTextMessage(
+	client: SeaTalkClient,
+	employeeCode: string,
+	text: string,
+	format: 1 | 2 = 1,
+	threadId?: string,
+): Promise<void> {
+	await client.sendSingleChat(
+		employeeCode,
+		{ tag: "text", text: { format, content: text } },
+		threadId,
+	);
+}
+
+export async function sendImageMessage(
+	client: SeaTalkClient,
+	employeeCode: string,
+	base64Data: string,
+	threadId?: string,
+): Promise<void> {
+	await client.sendSingleChat(
+		employeeCode,
+		{ tag: "image", image: { content: base64Data } },
+		threadId,
+	);
+}
+
+export async function sendFileMessage(
+	client: SeaTalkClient,
+	employeeCode: string,
+	base64Data: string,
+	filename: string,
+	threadId?: string,
+): Promise<void> {
+	await client.sendSingleChat(
+		employeeCode,
+		{ tag: "file", file: { content: base64Data, filename } },
+		threadId,
+	);
+}
+
+export async function sendGroupTextMessage(
+	client: SeaTalkClient,
+	groupId: string,
+	text: string,
+	format: 1 | 2 = 1,
+	threadId?: string,
+): Promise<void> {
+	await client.sendGroupChat(groupId, { tag: "text", text: { format, content: text } }, threadId);
+}
+
+export async function sendSeaTalkMessage(params: {
+	cfg: ClawdbotConfig;
+	to: string;
+	text: string;
+	accountId?: string;
+}): Promise<{ messageId?: string; chatId?: string }> {
+	const { cfg, to, text, accountId } = params;
+	const account = resolveSeaTalkAccount({ cfg, accountId });
+	const client = resolveSeaTalkClient(account);
+	if (!client) {
+		throw new Error(`SeaTalk client not available for account ${account.accountId}`);
+	}
+
+	await sendTextMessage(client, to, text, 1);
+	return { chatId: to };
+}

package/src/targets.ts

@@ -0,0 +1,27 @@
+const GROUP_PREFIX = "group:";
+
+export function normalizeSeaTalkTarget(raw: string): string | null {
+	const trimmed = raw.trim();
+	if (!trimmed) return null;
+	return trimmed;
+}
+
+export function isGroupTarget(to: string): boolean {
+	return to.startsWith(GROUP_PREFIX);
+}
+
+export function parseGroupTarget(to: string): string {
+	return to.slice(GROUP_PREFIX.length);
+}
+
+export function looksLikeEmail(raw: string): boolean {
+	return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(raw.trim());
+}
+
+export function looksLikeSeaTalkId(raw: string): boolean {
+	const trimmed = raw.trim();
+	if (!trimmed) return false;
+	if (looksLikeEmail(trimmed)) return true;
+	if (isGroupTarget(trimmed)) return parseGroupTarget(trimmed).length > 0;
+	return /^[a-zA-Z0-9_-]+$/.test(trimmed);
+}

package/src/tool-schema.ts

@@ -0,0 +1,60 @@
+import { type Static, Type } from "@sinclair/typebox";
+
+const CURSOR_DESC =
+	"Pagination cursor. Omit for the first request to get the latest messages. To fetch older messages, pass the next_cursor value from the previous response.";
+
+export const SeaTalkToolSchema = Type.Union([
+	Type.Object({
+		action: Type.Literal("group_history", {
+			description:
+				"Get group chat message history (requires 'Get Chat History' app permission). Messages are returned in chronological order (oldest to newest). The first page (no cursor) contains the most recent messages. Use next_cursor from the response to fetch older pages.",
+		}),
+		group_id: Type.String({ description: "Group chat ID" }),
+		page_size: Type.Optional(Type.Number({ description: "Page size (1-100, default 50)" })),
+		cursor: Type.Optional(Type.String({ description: CURSOR_DESC })),
+	}),
+	Type.Object({
+		action: Type.Literal("group_info", { description: "Get group chat details" }),
+		group_id: Type.String({ description: "Group chat ID" }),
+	}),
+	Type.Object({
+		action: Type.Literal("group_list", {
+			description: "List groups the bot has joined",
+		}),
+		page_size: Type.Optional(Type.Number({ description: "Page size (1-100, default 50)" })),
+		cursor: Type.Optional(
+			Type.String({
+				description:
+					"Pagination cursor. Omit for the first request. To fetch more groups, pass the next_cursor value from the previous response.",
+			}),
+		),
+	}),
+	Type.Object({
+		action: Type.Literal("thread_history", {
+			description:
+				"Get thread messages in chronological order (oldest to newest). The first page (no cursor) contains the most recent replies. Use next_cursor to fetch older replies.",
+		}),
+		thread_id: Type.String({ description: "Thread ID" }),
+		group_id: Type.Optional(
+			Type.String({
+				description: "Group chat ID (provide for group thread, omit for DM thread)",
+			}),
+		),
+		employee_code: Type.Optional(
+			Type.String({
+				description: "Employee code (required for DM thread when group_id is omitted)",
+			}),
+		),
+		page_size: Type.Optional(Type.Number({ description: "Page size (1-100, default 50)" })),
+		cursor: Type.Optional(Type.String({ description: CURSOR_DESC })),
+	}),
+	Type.Object({
+		action: Type.Literal("get_message", {
+			description:
+				"Get a message by its ID. Can resolve any message_id or quoted_message_id.",
+		}),
+		message_id: Type.String({ description: "The message ID to retrieve" }),
+	}),
+]);
+
+export type SeaTalkToolParams = Static<typeof SeaTalkToolSchema>;

package/src/tool.ts

@@ -0,0 +1,180 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { listEnabledSeaTalkAccounts } from "./accounts.js";
+import type { SeaTalkClient } from "./client.js";
+import { resolveSeaTalkClient } from "./client.js";
+import { type SeaTalkToolParams, SeaTalkToolSchema } from "./tool-schema.js";
+import type { SeaTalkToolsConfig } from "./types.js";
+
+function json(data: unknown) {
+	return {
+		content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+		details: data,
+	};
+}
+
+type ResolvedToolsConfig = Required<SeaTalkToolsConfig>;
+
+function resolveToolsConfig(cfg?: SeaTalkToolsConfig): ResolvedToolsConfig {
+	return {
+		groupInfo: cfg?.groupInfo ?? true,
+		groupHistory: cfg?.groupHistory ?? true,
+		groupList: cfg?.groupList ?? true,
+		threadHistory: cfg?.threadHistory ?? true,
+		getMessage: cfg?.getMessage ?? true,
+	};
+}
+
+async function resolveQuotedMessages(
+	client: SeaTalkClient,
+	messages: Record<string, unknown>[],
+	log?: (msg: string) => void,
+): Promise<void> {
+	for (const msg of messages) {
+		if (!msg || typeof msg !== "object") continue;
+		const qid = msg.quoted_message_id;
+		if (!qid || typeof qid !== "string") continue;
+		try {
+			const quoted = await client.getMessageByMessageId(qid);
+			msg.quoted_message = quoted;
+		} catch (err) {
+			log?.(`seatalk tool: failed to resolve quoted message ${qid}: ${String(err)}`);
+			msg.quoted_message = null;
+		}
+	}
+}
+
+function reverseMessageArray(
+	data: Record<string, unknown>,
+	key: string,
+): Record<string, unknown>[] {
+	const arr = data[key];
+	if (Array.isArray(arr)) {
+		const reversed = (arr as Record<string, unknown>[]).toReversed();
+		data[key] = reversed;
+		return reversed;
+	}
+	return [];
+}
+
+export function registerSeaTalkTool(api: OpenClawPluginApi) {
+	if (!api.config) {
+		api.logger.debug?.("seatalk tool: No config available, skipping");
+		return;
+	}
+
+	const accounts = listEnabledSeaTalkAccounts(api.config);
+	if (accounts.length === 0) {
+		api.logger.debug?.("seatalk tool: No enabled SeaTalk accounts, skipping");
+		return;
+	}
+
+	const firstAccount = accounts[0];
+	const toolsCfg = resolveToolsConfig(firstAccount.tools);
+
+	const anyEnabled =
+		toolsCfg.groupInfo ||
+		toolsCfg.groupHistory ||
+		toolsCfg.groupList ||
+		toolsCfg.threadHistory ||
+		toolsCfg.getMessage;
+	if (!anyEnabled) {
+		api.logger.debug?.("seatalk tool: All actions disabled, skipping");
+		return;
+	}
+
+	const getClient = () => resolveSeaTalkClient(firstAccount);
+	const log = (msg: string) => api.logger.warn?.(msg);
+
+	api.registerTool(
+		{
+			name: "seatalk",
+			label: "SeaTalk",
+			description:
+				"SeaTalk operations. Actions: group_history (group chat messages, chronological order), group_info (group details), group_list (joined groups), thread_history (thread messages, chronological order), get_message (retrieve a single message by ID). History and thread results include resolved quoted_message for messages that quote another message.",
+			parameters: SeaTalkToolSchema,
+			async execute(_toolCallId, params) {
+				const p = params as SeaTalkToolParams;
+				try {
+					const client = getClient();
+					if (!client) {
+						return json({ error: "SeaTalk client not available" });
+					}
+
+					switch (p.action) {
+						case "group_history": {
+							if (!toolsCfg.groupHistory) {
+								return json({ error: "groupHistory is disabled in config" });
+							}
+							const data = await client.getGroupChatHistory(p.group_id, {
+								pageSize: p.page_size,
+								cursor: p.cursor,
+							});
+							const msgs = reverseMessageArray(data, "group_chat_messages");
+							await resolveQuotedMessages(client, msgs, log);
+							return json(data);
+						}
+						case "group_info": {
+							if (!toolsCfg.groupInfo) {
+								return json({ error: "groupInfo is disabled in config" });
+							}
+							return json(await client.getGroupChatInfo(p.group_id));
+						}
+						case "group_list": {
+							if (!toolsCfg.groupList) {
+								return json({ error: "groupList is disabled in config" });
+							}
+							return json(
+								await client.getJoinedGroupChats({
+									pageSize: p.page_size,
+									cursor: p.cursor,
+								}),
+							);
+						}
+						case "thread_history": {
+							if (!toolsCfg.threadHistory) {
+								return json({ error: "threadHistory is disabled in config" });
+							}
+							let data: Record<string, unknown>;
+							if (p.group_id) {
+								data = await client.getGroupThread(p.group_id, p.thread_id, {
+									pageSize: p.page_size,
+									cursor: p.cursor,
+								});
+							} else {
+								if (!p.employee_code) {
+									return json({
+										error: "employee_code is required for DM thread (when group_id is absent)",
+									});
+								}
+								data = await client.getDmThread(p.employee_code, p.thread_id, {
+									pageSize: p.page_size,
+									cursor: p.cursor,
+								});
+							}
+							const msgs = reverseMessageArray(data, "thread_messages");
+							await resolveQuotedMessages(client, msgs, log);
+							return json(data);
+						}
+						case "get_message": {
+							if (!toolsCfg.getMessage) {
+								return json({ error: "getMessage is disabled in config" });
+							}
+							return json(await client.getMessageByMessageId(p.message_id));
+						}
+						default:
+							return json({
+								error: `Unknown action: ${String((p as Record<string, unknown>).action)}`,
+							});
+					}
+				} catch (err) {
+					return json({
+						error: err instanceof Error ? err.message : String(err),
+					});
+				}
+			},
+		},
+		{ name: "seatalk" },
+	);
+
+	api.logger.info?.("seatalk tool: Registered");
+}

package/src/types.ts

@@ -0,0 +1,94 @@
+import type {
+	SeaTalkAccountConfigSchema,
+	SeaTalkConfigSchema,
+	SeaTalkToolsConfigSchema,
+	z,
+} from "./config-schema.js";
+
+export type SeaTalkConfig = z.infer<typeof SeaTalkConfigSchema>;
+export type SeaTalkAccountConfig = z.infer<typeof SeaTalkAccountConfigSchema>;
+export type SeaTalkToolsConfig = z.infer<typeof SeaTalkToolsConfigSchema>;
+
+export type GatewayMode = "webhook" | "relay";
+
+export type ResolvedSeaTalkAccount = {
+	accountId: string;
+	enabled: boolean;
+	configured: boolean;
+	appId?: string;
+	appSecret?: string;
+	signingSecret?: string;
+	mode: GatewayMode;
+	relayUrl?: string;
+	webhookPort: number;
+	webhookPath: string;
+	tools?: SeaTalkToolsConfig;
+	config: SeaTalkConfig;
+};
+
+export type SeaTalkCallbackRequest = {
+	event_id: string;
+	event_type: string;
+	timestamp: number;
+	app_id: string;
+	event: Record<string, unknown>;
+};
+
+export type SeaTalkMessageEvent = {
+	seatalk_id: string;
+	employee_code: string;
+	email?: string;
+	message: SeaTalkMessage;
+};
+
+export type SeaTalkGroupMessageEvent = {
+	group_id: string;
+	message: SeaTalkGroupMessage;
+};
+
+export type SeaTalkGroupMessage = SeaTalkMessage & {
+	sender: {
+		seatalk_id: string;
+		employee_code: string;
+		email?: string;
+		sender_type?: number;
+	};
+	message_sent_time?: number;
+};
+
+export type SeaTalkMessage = {
+	message_id: string;
+	quoted_message_id?: string;
+	thread_id?: string;
+	tag: "text" | "image" | "file" | "video" | "combined_forwarded_chat_history";
+	text?: { content?: string; plain_text?: string };
+	image?: { content: string };
+	file?: { content: string; filename: string };
+	video?: { content: string };
+};
+
+export type SeaTalkMediaInfo = {
+	path: string;
+	contentType?: string;
+	filename?: string;
+	placeholder: string;
+};
+
+export type SeaTalkOutboundMedia = {
+	base64: string;
+	sendAs: "image" | "file";
+	filename?: string;
+};
+
+export type SeaTalkProbeResult = {
+	ok: boolean;
+	error?: string;
+	appId?: string;
+	tokenExpire?: number;
+	latencyMs?: number;
+};
+
+export type SeaTalkTokenInfo = {
+	token: string;
+	expireAt: number;
+};