openclaw-seatalk 0.1.0

package/src/onboarding.ts

@@ -0,0 +1,507 @@
+import type {
+	ChannelOnboardingAdapter,
+	ChannelOnboardingDmPolicy,
+	ClawdbotConfig,
+	DmPolicy,
+	WizardPrompter,
+} from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, addWildcardAllowFrom } from "openclaw/plugin-sdk";
+import { resolveSeaTalkCredentials } from "./accounts.js";
+import { probeSeaTalk } from "./probe.js";
+import type { SeaTalkConfig } from "./types.js";
+
+const channel = "seatalk" as const;
+
+function setSeaTalkDmPolicy(cfg: ClawdbotConfig, dmPolicy: DmPolicy): ClawdbotConfig {
+	const allowFrom =
+		dmPolicy === "open"
+			? addWildcardAllowFrom(cfg.channels?.seatalk?.allowFrom)?.map((entry) => String(entry))
+			: undefined;
+	return {
+		...cfg,
+		channels: {
+			...cfg.channels,
+			seatalk: {
+				...cfg.channels?.seatalk,
+				dmPolicy,
+				...(allowFrom ? { allowFrom } : {}),
+			},
+		},
+	};
+}
+
+function setSeaTalkAllowFrom(cfg: ClawdbotConfig, allowFrom: string[]): ClawdbotConfig {
+	return {
+		...cfg,
+		channels: {
+			...cfg.channels,
+			seatalk: {
+				...cfg.channels?.seatalk,
+				allowFrom,
+			},
+		},
+	};
+}
+
+function parseAllowFromInput(raw: string): string[] {
+	return raw
+		.split(/[\n,;]+/g)
+		.map((entry) => entry.trim())
+		.filter(Boolean);
+}
+
+async function promptSeaTalkAllowFrom(params: {
+	cfg: ClawdbotConfig;
+	prompter: WizardPrompter;
+}): Promise<ClawdbotConfig> {
+	const existing = params.cfg.channels?.seatalk?.allowFrom ?? [];
+	await params.prompter.note(
+		[
+			"Allowlist SeaTalk DMs by email or employee_code.",
+			"Examples:",
+			"- alice@company.com",
+			"- e_12345678",
+		].join("\n"),
+		"SeaTalk allowlist",
+	);
+
+	while (true) {
+		const entry = await params.prompter.text({
+			message: "SeaTalk allowFrom (emails or employee_codes)",
+			placeholder: "alice@company.com, e_xxxxx",
+			initialValue: existing[0] ? String(existing[0]) : undefined,
+			validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+		});
+		const parts = parseAllowFromInput(String(entry));
+		if (parts.length === 0) {
+			await params.prompter.note("Enter at least one user.", "SeaTalk allowlist");
+			continue;
+		}
+
+		const unique = [
+			...new Set([
+				...existing.map((v: string | number) => String(v).trim()).filter(Boolean),
+				...parts,
+			]),
+		];
+		return setSeaTalkAllowFrom(params.cfg, unique);
+	}
+}
+
+async function promptCredentials(prompter: WizardPrompter): Promise<{
+	appId: string;
+	appSecret: string;
+	signingSecret: string;
+}> {
+	const appId = String(
+		await prompter.text({
+			message: "Enter SeaTalk App ID",
+			validate: (value) => (value?.trim() ? undefined : "Required"),
+		}),
+	).trim();
+	const appSecret = String(
+		await prompter.text({
+			message: "Enter SeaTalk App Secret",
+			validate: (value) => (value?.trim() ? undefined : "Required"),
+		}),
+	).trim();
+	const signingSecret = String(
+		await prompter.text({
+			message: "Enter SeaTalk Signing Secret",
+			validate: (value) => (value?.trim() ? undefined : "Required"),
+		}),
+	).trim();
+	return { appId, appSecret, signingSecret };
+}
+
+async function noteSeaTalkCredentialHelp(prompter: WizardPrompter): Promise<void> {
+	await prompter.note(
+		[
+			"1) Go to SeaTalk Open Platform (open.seatalk.io)",
+			"2) Create a Bot App",
+			"3) Get App ID and App Secret from Basic Info & Credentials",
+			"4) Get Signing Secret from Event Callback settings",
+			"5) Enable Bot capability and set status to Online",
+			'6) Enable "Send Message to Bot User" permission',
+			"Tip: you can also set SEATALK_APP_ID / SEATALK_APP_SECRET / SEATALK_SIGNING_SECRET env vars.",
+		].join("\n"),
+		"SeaTalk credentials",
+	);
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+	label: "SeaTalk",
+	channel,
+	policyKey: "channels.seatalk.dmPolicy",
+	allowFromKey: "channels.seatalk.allowFrom",
+	getCurrent: (cfg) =>
+		(cfg.channels?.seatalk as SeaTalkConfig | undefined)?.dmPolicy ?? "allowlist",
+	setPolicy: (cfg, policy) => setSeaTalkDmPolicy(cfg, policy),
+	promptAllowFrom: promptSeaTalkAllowFrom,
+};
+
+export const seatalkOnboardingAdapter: ChannelOnboardingAdapter = {
+	channel,
+	getStatus: async ({ cfg }) => {
+		const seatalkCfg = cfg.channels?.seatalk as SeaTalkConfig | undefined;
+		const configured = Boolean(resolveSeaTalkCredentials(seatalkCfg));
+
+		let probeResult = null;
+		if (configured && seatalkCfg) {
+			try {
+				probeResult = await probeSeaTalk({
+					appId: seatalkCfg.appId,
+					appSecret: seatalkCfg.appSecret,
+				});
+			} catch {
+				// ignore
+			}
+		}
+
+		const statusLines: string[] = [];
+		if (!configured) {
+			statusLines.push("SeaTalk: needs app credentials");
+		} else if (probeResult?.ok) {
+			statusLines.push(
+				`SeaTalk: connected (appId: ${probeResult.appId}, latency: ${probeResult.latencyMs}ms)`,
+			);
+		} else {
+			statusLines.push("SeaTalk: configured (connection not verified)");
+		}
+
+		return {
+			channel,
+			configured,
+			statusLines,
+			selectionHint: configured ? "configured" : "needs app creds",
+			quickstartScore: configured ? 2 : 0,
+		};
+	},
+
+	configure: async ({ cfg, prompter, forceAllowFrom }) => {
+		const seatalkCfg = cfg.channels?.seatalk as SeaTalkConfig | undefined;
+		const resolved = resolveSeaTalkCredentials(seatalkCfg);
+		const hasConfigCreds = Boolean(
+			seatalkCfg?.appId?.trim() &&
+				seatalkCfg?.appSecret?.trim() &&
+				seatalkCfg?.signingSecret?.trim(),
+		);
+		const canUseEnv = Boolean(
+			!hasConfigCreds &&
+				process.env.SEATALK_APP_ID?.trim() &&
+				process.env.SEATALK_APP_SECRET?.trim() &&
+				process.env.SEATALK_SIGNING_SECRET?.trim(),
+		);
+
+		let next = cfg;
+		let appId: string | null = null;
+		let appSecret: string | null = null;
+		let signingSecret: string | null = null;
+
+		if (!resolved) {
+			await noteSeaTalkCredentialHelp(prompter);
+		}
+
+		if (canUseEnv) {
+			const keepEnv = await prompter.confirm({
+				message:
+					"SEATALK_APP_ID + SEATALK_APP_SECRET + SEATALK_SIGNING_SECRET detected. Use env vars?",
+				initialValue: true,
+			});
+			if (keepEnv) {
+				next = {
+					...next,
+					channels: {
+						...next.channels,
+						seatalk: {
+							...next.channels?.seatalk,
+							enabled: true,
+							dmPolicy:
+								(next.channels?.seatalk as SeaTalkConfig | undefined)?.dmPolicy ??
+								"allowlist",
+						},
+					},
+				};
+			} else {
+				({ appId, appSecret, signingSecret } = await promptCredentials(prompter));
+			}
+		} else if (hasConfigCreds) {
+			const keep = await prompter.confirm({
+				message: "SeaTalk credentials already configured. Keep them?",
+				initialValue: true,
+			});
+			if (!keep) {
+				({ appId, appSecret, signingSecret } = await promptCredentials(prompter));
+			}
+		} else {
+			({ appId, appSecret, signingSecret } = await promptCredentials(prompter));
+		}
+
+		if (appId && appSecret && signingSecret) {
+			next = {
+				...next,
+				channels: {
+					...next.channels,
+					seatalk: {
+						...next.channels?.seatalk,
+						enabled: true,
+						appId,
+						appSecret,
+						signingSecret,
+						dmPolicy:
+							(next.channels?.seatalk as SeaTalkConfig | undefined)?.dmPolicy ??
+							"allowlist",
+					},
+				},
+			};
+
+			try {
+				const probe = await probeSeaTalk({ appId, appSecret });
+				if (probe.ok) {
+					await prompter.note(
+						`Connected successfully (latency: ${probe.latencyMs}ms)`,
+						"SeaTalk connection test",
+					);
+				} else {
+					await prompter.note(
+						`Connection failed: ${probe.error ?? "unknown error"}`,
+						"SeaTalk connection test",
+					);
+				}
+			} catch (err) {
+				await prompter.note(
+					`Connection test failed: ${String(err)}`,
+					"SeaTalk connection test",
+				);
+			}
+
+			await prompter.note(
+				[
+					"Important reminders:",
+					'- Bot App must be set to "Online" status in SeaTalk Open Platform',
+					'- "Send Message to Bot User" permission must be enabled',
+					"- Configure the callback URL in Event Callback settings",
+				].join("\n"),
+				"SeaTalk setup",
+			);
+		}
+
+		const currentMode =
+			(next.channels?.seatalk as SeaTalkConfig | undefined)?.mode ?? "webhook";
+		const modeChoice = await prompter.select({
+			message: "Gateway mode",
+			options: [
+				{ value: "webhook", label: "Webhook — receive event callbacks directly (default)" },
+				{ value: "relay", label: "Relay — connect to a relay service as client" },
+			],
+			initialValue: currentMode,
+		});
+		const mode = String(modeChoice) as "webhook" | "relay";
+
+		next = {
+			...next,
+			channels: {
+				...next.channels,
+				seatalk: {
+					...next.channels?.seatalk,
+					mode,
+				},
+			},
+		};
+
+		if (mode === "relay") {
+			const currentRelayUrl =
+				(next.channels?.seatalk as SeaTalkConfig | undefined)?.relayUrl ?? "";
+			const relayUrlInput = await prompter.text({
+				message: "Relay WebSocket URL",
+				placeholder: "ws://relay.example.com:8080/ws",
+				initialValue: currentRelayUrl || undefined,
+				validate: (value) => {
+					const v = String(value ?? "").trim();
+					if (!v) return "Required";
+					if (!v.startsWith("ws://") && !v.startsWith("wss://"))
+						return "Must be a ws:// or wss:// URL";
+					return undefined;
+				},
+			});
+			const relayUrl = String(relayUrlInput).trim();
+			next = {
+				...next,
+				channels: {
+					...next.channels,
+					seatalk: {
+						...next.channels?.seatalk,
+						relayUrl,
+					},
+				},
+			};
+		} else {
+			const currentPort =
+				(next.channels?.seatalk as SeaTalkConfig | undefined)?.webhookPort ?? 8080;
+			const portInput = await prompter.text({
+				message: "Webhook port",
+				initialValue: String(currentPort),
+				validate: (value) => {
+					const n = Number(value);
+					return n > 0 && n < 65536 ? undefined : "Enter a valid port number (1-65535)";
+				},
+			});
+			const port = Number(portInput);
+			if (port && port !== currentPort) {
+				next = {
+					...next,
+					channels: {
+						...next.channels,
+						seatalk: {
+							...next.channels?.seatalk,
+							webhookPort: port,
+						},
+					},
+				};
+			}
+
+			const currentPath =
+				(next.channels?.seatalk as SeaTalkConfig | undefined)?.webhookPath ?? "/callback";
+			const pathInput = await prompter.text({
+				message: "Webhook path",
+				initialValue: currentPath,
+				validate: (value) => {
+					const v = String(value ?? "").trim();
+					if (!v) return "Required";
+					if (!v.startsWith("/")) return "Path must start with /";
+					return undefined;
+				},
+			});
+			const webhookPath = String(pathInput ?? currentPath).trim();
+			if (webhookPath && webhookPath !== currentPath) {
+				next = {
+					...next,
+					channels: {
+						...next.channels,
+						seatalk: {
+							...next.channels?.seatalk,
+							webhookPath,
+						},
+					},
+				};
+			}
+		}
+
+		const groupPolicyChoice = await prompter.select({
+			message: "Group chat policy",
+			options: [
+				{ value: "disabled", label: "Disabled — ignore all group messages (default)" },
+				{ value: "allowlist", label: "Allowlist — respond only in specific groups" },
+				{ value: "open", label: "Open — respond in all groups the bot joins" },
+			],
+			initialValue:
+				(next.channels?.seatalk as SeaTalkConfig | undefined)?.groupPolicy ?? "disabled",
+		});
+		const groupPolicy = String(groupPolicyChoice) as "disabled" | "allowlist" | "open";
+
+		next = {
+			...next,
+			channels: {
+				...next.channels,
+				seatalk: {
+					...next.channels?.seatalk,
+					groupPolicy,
+				},
+			},
+		};
+
+		if (groupPolicy === "allowlist") {
+			const existingGroups =
+				(next.channels?.seatalk as SeaTalkConfig | undefined)?.groupAllowFrom ?? [];
+			const groupInput = await prompter.text({
+				message: "Allowed group IDs (comma-separated)",
+				placeholder: "group_abc123, group_def456",
+				initialValue: existingGroups.length > 0 ? existingGroups.join(", ") : undefined,
+				validate: (value) =>
+					String(value ?? "").trim() ? undefined : "Enter at least one group ID",
+			});
+			const groupAllowFrom = parseAllowFromInput(String(groupInput));
+			next = {
+				...next,
+				channels: {
+					...next.channels,
+					seatalk: {
+						...next.channels?.seatalk,
+						groupAllowFrom,
+					},
+				},
+			};
+		}
+
+		if (groupPolicy !== "disabled") {
+			const wantSenderFilter = await prompter.confirm({
+				message: "Restrict which users can trigger the bot in groups? (sender allowlist)",
+				initialValue: true,
+			});
+			if (wantSenderFilter) {
+				const existingSenders =
+					(next.channels?.seatalk as SeaTalkConfig | undefined)?.groupSenderAllowFrom ??
+					[];
+				const senderInput = await prompter.text({
+					message: "Sender allowlist (emails or employee_codes, comma-separated)",
+					placeholder: "alice@company.com, e_12345678",
+					initialValue:
+						existingSenders.length > 0 ? existingSenders.join(", ") : undefined,
+					validate: (value) =>
+						String(value ?? "").trim() ? undefined : "Enter at least one user",
+				});
+				const groupSenderAllowFrom = parseAllowFromInput(String(senderInput));
+				next = {
+					...next,
+					channels: {
+						...next.channels,
+						seatalk: {
+							...next.channels?.seatalk,
+							groupSenderAllowFrom,
+						},
+					},
+				};
+			}
+		}
+
+		const typingChoice = await prompter.select({
+			message: "Typing indicator",
+			options: [
+				{
+					value: "typing",
+					label: "Typing — show typing status while processing (default)",
+				},
+				{ value: "off", label: "Off — no typing indicator" },
+			],
+			initialValue:
+				(next.channels?.seatalk as SeaTalkConfig | undefined)?.processingIndicator ??
+				"typing",
+		});
+		next = {
+			...next,
+			channels: {
+				...next.channels,
+				seatalk: {
+					...next.channels?.seatalk,
+					processingIndicator: String(typingChoice),
+				},
+			},
+		};
+
+		if (forceAllowFrom) {
+			next = await promptSeaTalkAllowFrom({ cfg: next, prompter });
+		}
+
+		return { cfg: next, accountId: DEFAULT_ACCOUNT_ID };
+	},
+
+	dmPolicy,
+
+	disable: (cfg) => ({
+		...cfg,
+		channels: {
+			...cfg.channels,
+			seatalk: { ...cfg.channels?.seatalk, enabled: false },
+		},
+	}),
+};

package/src/outbound.ts

@@ -0,0 +1,120 @@
+import type { ChannelOutboundAdapter, ClawdbotConfig } from "openclaw/plugin-sdk";
+import { resolveSeaTalkAccount } from "./accounts.js";
+import { type SeaTalkClient, resolveSeaTalkClient } from "./client.js";
+import { prepareOutboundMedia } from "./media.js";
+import { getSeatalkRuntime } from "./runtime.js";
+import {
+	sendFileMessage,
+	sendGroupTextMessage,
+	sendImageMessage,
+	sendTextMessage,
+} from "./send.js";
+import { isGroupTarget, looksLikeEmail, parseGroupTarget } from "./targets.js";
+
+function requireClient(cfg: ClawdbotConfig, accountId?: string): SeaTalkClient {
+	const account = resolveSeaTalkAccount({ cfg, accountId });
+	const client = resolveSeaTalkClient(account);
+	if (!client) {
+		throw new Error(`SeaTalk client not available for account ${account.accountId}`);
+	}
+	return client;
+}
+
+async function resolveEmployeeCode(client: SeaTalkClient, to: string): Promise<string> {
+	if (!looksLikeEmail(to)) return to;
+	const results = await client.getEmployeeCodeByEmail([to]);
+	const active = results.find((r) => r.employeeCode && r.status === 2);
+	if (active?.employeeCode) return active.employeeCode;
+	throw new Error(`No active SeaTalk employee found for email: ${to}`);
+}
+
+function resolveThreadId(threadId?: string | number | null): string | undefined {
+	if (threadId === null || threadId === undefined) return undefined;
+	return String(threadId);
+}
+
+export const seatalkOutbound: ChannelOutboundAdapter = {
+	deliveryMode: "direct",
+	chunker: (text, limit) => getSeatalkRuntime().channel.text.chunkMarkdownText(text, limit),
+	chunkerMode: "markdown",
+	textChunkLimit: 4000,
+
+	sendText: async ({ cfg, to, text, accountId, threadId }) => {
+		const client = requireClient(cfg, accountId ?? undefined);
+		const tid = resolveThreadId(threadId);
+
+		if (isGroupTarget(to)) {
+			const groupId = parseGroupTarget(to);
+			await sendGroupTextMessage(client, groupId, text, 1, tid);
+			return { channel: "seatalk", messageId: "", chatId: to };
+		}
+
+		const employeeCode = await resolveEmployeeCode(client, to);
+		await sendTextMessage(client, employeeCode, text, 1, tid);
+		return { channel: "seatalk", messageId: "", chatId: employeeCode };
+	},
+
+	sendMedia: async ({ cfg, to, text, mediaUrl, accountId, threadId }) => {
+		const client = requireClient(cfg, accountId ?? undefined);
+		const tid = resolveThreadId(threadId);
+
+		if (isGroupTarget(to)) {
+			const groupId = parseGroupTarget(to);
+			if (text?.trim()) {
+				await sendGroupTextMessage(client, groupId, text, 1, tid);
+			}
+			if (mediaUrl) {
+				try {
+					const media = await prepareOutboundMedia(mediaUrl);
+					if (media) {
+						if (media.sendAs === "image") {
+							await client.sendGroupChat(
+								groupId,
+								{ tag: "image", image: { content: media.base64 } },
+								tid,
+							);
+						} else {
+							await client.sendGroupChat(
+								groupId,
+								{
+									tag: "file",
+									file: {
+										content: media.base64,
+										filename: media.filename || "file",
+									},
+								},
+								tid,
+							);
+						}
+					}
+				} catch (err) {
+					const fallbackText = `[Media send failed: ${err instanceof Error ? err.message : String(err)}]`;
+					await sendGroupTextMessage(client, groupId, fallbackText, 2, tid);
+				}
+			}
+			return { channel: "seatalk", messageId: "", chatId: to };
+		}
+
+		const employeeCode = await resolveEmployeeCode(client, to);
+		if (text?.trim()) {
+			await sendTextMessage(client, employeeCode, text, 1, tid);
+		}
+		if (mediaUrl) {
+			try {
+				const media = await prepareOutboundMedia(mediaUrl);
+				if (media) {
+					if (media.sendAs === "image") {
+						await sendImageMessage(client, employeeCode, media.base64, tid);
+					} else {
+						const filename = media.filename || "file";
+						await sendFileMessage(client, employeeCode, media.base64, filename, tid);
+					}
+				}
+			} catch (err) {
+				const fallbackText = `[Media send failed: ${err instanceof Error ? err.message : String(err)}]`;
+				await sendTextMessage(client, employeeCode, fallbackText, 2, tid);
+			}
+		}
+		return { channel: "seatalk", messageId: "", chatId: employeeCode };
+	},
+};

package/src/probe.ts

@@ -0,0 +1,34 @@
+import { SeaTalkClient } from "./client.js";
+import type { SeaTalkProbeResult } from "./types.js";
+
+export async function probeSeaTalk(params?: {
+	appId?: string;
+	appSecret?: string;
+}): Promise<SeaTalkProbeResult> {
+	if (!params?.appId || !params?.appSecret) {
+		return {
+			ok: false,
+			error: "missing credentials (appId, appSecret)",
+		};
+	}
+
+	try {
+		const client = new SeaTalkClient(params.appId, params.appSecret);
+		const start = Date.now();
+		const tokenInfo = await client.refreshToken();
+		const latencyMs = Date.now() - start;
+
+		return {
+			ok: true,
+			appId: params.appId,
+			tokenExpire: tokenInfo.expireAt,
+			latencyMs,
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			appId: params.appId,
+			error: err instanceof Error ? err.message : String(err),
+		};
+	}
+}