openclaw-seatalk 0.1.0

package/src/channel.ts

@@ -0,0 +1,359 @@
+import type { ChannelMeta, ChannelPlugin, ClawdbotConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import {
+	listSeaTalkAccountIds,
+	resolveDefaultSeaTalkAccountId,
+	resolveSeaTalkAccount,
+} from "./accounts.js";
+import { resolveSeaTalkClient } from "./client.js";
+import { seatalkOnboardingAdapter } from "./onboarding.js";
+import { seatalkOutbound } from "./outbound.js";
+import { probeSeaTalk } from "./probe.js";
+import { looksLikeEmail, looksLikeSeaTalkId, normalizeSeaTalkTarget } from "./targets.js";
+import type { ResolvedSeaTalkAccount, SeaTalkConfig } from "./types.js";
+
+const meta: ChannelMeta = {
+	id: "seatalk",
+	label: "SeaTalk",
+	selectionLabel: "SeaTalk (plugin)",
+	blurb: "SeaTalk internal messaging integration.",
+	docsPath: "/channels/seatalk",
+	aliases: [],
+	order: 70,
+	quickstartAllowFrom: true,
+};
+
+export const seatalkPlugin: ChannelPlugin<ResolvedSeaTalkAccount> = {
+	id: "seatalk",
+	meta,
+	capabilities: {
+		chatTypes: ["direct", "group"],
+		polls: false,
+		threads: true,
+		media: true,
+		reactions: false,
+		edit: false,
+		reply: false,
+	},
+	reload: { configPrefixes: ["channels.seatalk"] },
+	configSchema: {
+		schema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				enabled: { type: "boolean" },
+				appId: { type: "string" },
+				appSecret: { type: "string" },
+				signingSecret: { type: "string" },
+				mode: { type: "string", enum: ["webhook", "relay"] },
+				relayUrl: { type: "string" },
+				webhookPort: { type: "integer", minimum: 1 },
+				webhookPath: { type: "string" },
+				dmPolicy: { type: "string", enum: ["open", "allowlist"] },
+				allowFrom: { type: "array", items: { type: "string" } },
+				groupPolicy: { type: "string", enum: ["disabled", "allowlist", "open"] },
+				groupAllowFrom: { type: "array", items: { type: "string" } },
+				groupSenderAllowFrom: { type: "array", items: { type: "string" } },
+				processingIndicator: { type: "string", enum: ["typing", "off"] },
+				tools: {
+					type: "object",
+					properties: {
+						groupInfo: { type: "boolean" },
+						groupHistory: { type: "boolean" },
+						groupList: { type: "boolean" },
+						threadHistory: { type: "boolean" },
+						getMessage: { type: "boolean" },
+					},
+				},
+				accounts: {
+					type: "object",
+					additionalProperties: {
+						type: "object",
+						properties: {
+							enabled: { type: "boolean" },
+							appId: { type: "string" },
+							appSecret: { type: "string" },
+							signingSecret: { type: "string" },
+							mode: { type: "string", enum: ["webhook", "relay"] },
+							relayUrl: { type: "string" },
+							webhookPort: { type: "integer", minimum: 1 },
+							webhookPath: { type: "string" },
+							dmPolicy: { type: "string", enum: ["open", "allowlist"] },
+							allowFrom: { type: "array", items: { type: "string" } },
+							groupPolicy: {
+								type: "string",
+								enum: ["disabled", "allowlist", "open"],
+							},
+							groupAllowFrom: { type: "array", items: { type: "string" } },
+							groupSenderAllowFrom: { type: "array", items: { type: "string" } },
+							processingIndicator: { type: "string", enum: ["typing", "off"] },
+						},
+					},
+				},
+			},
+		},
+	},
+	config: {
+		listAccountIds: (cfg) => listSeaTalkAccountIds(cfg),
+		resolveAccount: (cfg, accountId) => resolveSeaTalkAccount({ cfg, accountId }),
+		defaultAccountId: (cfg) => resolveDefaultSeaTalkAccountId(cfg),
+		setAccountEnabled: ({ cfg, accountId, enabled }) => {
+			const isDefault = accountId === DEFAULT_ACCOUNT_ID;
+
+			if (isDefault) {
+				return {
+					...cfg,
+					channels: {
+						...cfg.channels,
+						seatalk: {
+							...cfg.channels?.seatalk,
+							enabled,
+						},
+					},
+				};
+			}
+
+			const seatalkCfg = cfg.channels?.seatalk as SeaTalkConfig | undefined;
+			return {
+				...cfg,
+				channels: {
+					...cfg.channels,
+					seatalk: {
+						...seatalkCfg,
+						accounts: {
+							...seatalkCfg?.accounts,
+							[accountId]: {
+								...seatalkCfg?.accounts?.[accountId],
+								enabled,
+							},
+						},
+					},
+				},
+			};
+		},
+		deleteAccount: ({ cfg, accountId }) => {
+			const isDefault = accountId === DEFAULT_ACCOUNT_ID;
+
+			if (isDefault) {
+				const next = { ...cfg } as ClawdbotConfig;
+				const nextChannels = { ...cfg.channels } as Record<string, unknown>;
+				nextChannels.seatalk = undefined;
+				const hasOtherChannels = Object.values(nextChannels).some((v) => v !== undefined);
+				next.channels = hasOtherChannels ? nextChannels : undefined;
+				return next;
+			}
+
+			const seatalkCfg = cfg.channels?.seatalk as SeaTalkConfig | undefined;
+			const accounts = { ...seatalkCfg?.accounts };
+			delete accounts[accountId];
+
+			return {
+				...cfg,
+				channels: {
+					...cfg.channels,
+					seatalk: {
+						...seatalkCfg,
+						accounts: Object.keys(accounts).length > 0 ? accounts : undefined,
+					},
+				},
+			};
+		},
+		isConfigured: (account) => account.configured,
+		describeAccount: (account) => ({
+			accountId: account.accountId,
+			enabled: account.enabled,
+			configured: account.configured,
+			appId: account.appId,
+			mode: account.mode,
+			...(account.mode === "relay"
+				? { relayUrl: account.relayUrl }
+				: { webhookPort: account.webhookPort }),
+		}),
+		resolveAllowFrom: ({ cfg, accountId }) => {
+			const account = resolveSeaTalkAccount({ cfg, accountId });
+			return (account.config?.allowFrom ?? []).map((entry) => String(entry));
+		},
+		formatAllowFrom: ({ allowFrom }) =>
+			allowFrom.map((entry) => String(entry).trim()).filter(Boolean),
+	},
+	security: {
+		collectWarnings: ({ cfg, accountId }) => {
+			const account = resolveSeaTalkAccount({ cfg, accountId });
+			const seatalkCfg = account.config;
+			const dmPolicy = seatalkCfg?.dmPolicy ?? "allowlist";
+			if (dmPolicy !== "open") return [];
+			return [
+				`- SeaTalk[${account.accountId}]: dmPolicy="open" allows any subscriber to message the bot. Set channels.seatalk.dmPolicy="allowlist" + channels.seatalk.allowFrom to restrict senders.`,
+			];
+		},
+	},
+	setup: {
+		resolveAccountId: () => DEFAULT_ACCOUNT_ID,
+		applyAccountConfig: ({ cfg, accountId }) => {
+			const isDefault = !accountId || accountId === DEFAULT_ACCOUNT_ID;
+
+			if (isDefault) {
+				return {
+					...cfg,
+					channels: {
+						...cfg.channels,
+						seatalk: {
+							...cfg.channels?.seatalk,
+							enabled: true,
+						},
+					},
+				};
+			}
+
+			const seatalkCfg = cfg.channels?.seatalk as SeaTalkConfig | undefined;
+			return {
+				...cfg,
+				channels: {
+					...cfg.channels,
+					seatalk: {
+						...seatalkCfg,
+						accounts: {
+							...seatalkCfg?.accounts,
+							[accountId]: {
+								...seatalkCfg?.accounts?.[accountId],
+								enabled: true,
+							},
+						},
+					},
+				},
+			};
+		},
+	},
+	onboarding: seatalkOnboardingAdapter,
+	messaging: {
+		normalizeTarget: (raw) => normalizeSeaTalkTarget(raw) ?? undefined,
+		targetResolver: {
+			looksLikeId: looksLikeSeaTalkId,
+			hint: "<employee_code> or <email>",
+		},
+	},
+	resolver: {
+		resolveTargets: async ({ cfg, accountId, inputs }) => {
+			const emailInputs = inputs.filter((i) => looksLikeEmail(i));
+			if (emailInputs.length === 0) {
+				return inputs.map((input) => ({ input, resolved: true, id: input }));
+			}
+
+			const passNonEmails = (note: string) =>
+				inputs.map((input) => {
+					const isEmail = looksLikeEmail(input);
+					return {
+						input,
+						resolved: !isEmail,
+						id: isEmail ? undefined : input,
+						note: isEmail ? note : undefined,
+					};
+				});
+
+			const account = resolveSeaTalkAccount({ cfg, accountId });
+			const client = resolveSeaTalkClient(account);
+			if (!client) {
+				return passNonEmails("SeaTalk client not available");
+			}
+
+			const emailToCode = new Map<string, string>();
+			try {
+				const results = await client.getEmployeeCodeByEmail(emailInputs);
+				for (const r of results) {
+					if (r.employeeCode && r.status === 2) {
+						emailToCode.set(r.email.toLowerCase(), r.employeeCode);
+					}
+				}
+			} catch {
+				return passNonEmails("Failed to resolve email");
+			}
+
+			return inputs.map((input) => {
+				if (!looksLikeEmail(input)) {
+					return { input, resolved: true, id: input };
+				}
+				const code = emailToCode.get(input.toLowerCase());
+				if (code) {
+					return { input, resolved: true, id: code, name: input };
+				}
+				return { input, resolved: false, note: "No active employee found for this email" };
+			});
+		},
+	},
+	outbound: seatalkOutbound,
+	status: {
+		defaultRuntime: {
+			accountId: DEFAULT_ACCOUNT_ID,
+			running: false,
+			lastStartAt: null,
+			lastStopAt: null,
+			lastError: null,
+			port: null,
+		},
+		buildChannelSummary: ({ snapshot }) => ({
+			configured: snapshot.configured ?? false,
+			running: snapshot.running ?? false,
+			lastStartAt: snapshot.lastStartAt ?? null,
+			lastStopAt: snapshot.lastStopAt ?? null,
+			lastError: snapshot.lastError ?? null,
+			port: snapshot.port ?? null,
+			probe: snapshot.probe,
+			lastProbeAt: snapshot.lastProbeAt ?? null,
+		}),
+		probeAccount: ({ account }) => probeSeaTalk(account),
+		buildAccountSnapshot: ({ account, runtime, probe }) => ({
+			accountId: account.accountId,
+			enabled: account.enabled,
+			configured: account.configured,
+			appId: account.appId,
+			mode: account.mode,
+			...(account.mode === "relay"
+				? { relayUrl: account.relayUrl }
+				: { webhookPort: account.webhookPort }),
+			running: runtime?.running ?? false,
+			lastStartAt: runtime?.lastStartAt ?? null,
+			lastStopAt: runtime?.lastStopAt ?? null,
+			lastError: runtime?.lastError ?? null,
+			port: runtime?.port ?? null,
+			probe,
+		}),
+	},
+	gateway: {
+		startAccount: async (ctx) => {
+			const account = resolveSeaTalkAccount({ cfg: ctx.cfg, accountId: ctx.accountId });
+			const mode = account.mode;
+
+			if (mode === "relay") {
+				if (!account.relayUrl) {
+					throw new Error(
+						`SeaTalk account "${ctx.accountId}" mode=relay but relayUrl is not configured`,
+					);
+				}
+				ctx.setStatus({ accountId: ctx.accountId, mode: "relay" });
+				ctx.log?.info(
+					`starting seatalk[${ctx.accountId}] (relay client → ${account.relayUrl})`,
+				);
+				const { connectSeaTalkRelay } = await import("./relay-client.js");
+				return connectSeaTalkRelay({
+					config: ctx.cfg,
+					runtime: ctx.runtime,
+					abortSignal: ctx.abortSignal,
+					accountId: ctx.accountId,
+					relayUrl: account.relayUrl,
+				});
+			}
+
+			ctx.setStatus({ accountId: ctx.accountId, port: account.webhookPort });
+			ctx.log?.info(
+				`starting seatalk[${ctx.accountId}] (webhook on port ${account.webhookPort})`,
+			);
+			const { monitorSeaTalkProvider } = await import("./monitor.js");
+			return monitorSeaTalkProvider({
+				config: ctx.cfg,
+				runtime: ctx.runtime,
+				abortSignal: ctx.abortSignal,
+				accountId: ctx.accountId,
+			});
+		},
+	},
+};

package/src/client.ts

@@ -0,0 +1,329 @@
+import type { SeaTalkTokenInfo } from "./types.js";
+
+const BASE_URL = "https://openapi.seatalk.io";
+const HTTP_TIMEOUT_MS = 10_000;
+const TOKEN_REFRESH_MARGIN_S = 30;
+
+export class SeaTalkClient {
+	private appId: string;
+	private appSecret: string;
+	private tokenInfo: SeaTalkTokenInfo | null = null;
+	private tokenPromise: Promise<SeaTalkTokenInfo> | null = null;
+
+	constructor(appId: string, appSecret: string) {
+		this.appId = appId;
+		this.appSecret = appSecret;
+	}
+
+	async getAccessToken(): Promise<string> {
+		if (this.tokenInfo) {
+			const now = Math.floor(Date.now() / 1000);
+			if (this.tokenInfo.expireAt - now > TOKEN_REFRESH_MARGIN_S) {
+				return this.tokenInfo.token;
+			}
+		}
+		return (await this.refreshToken()).token;
+	}
+
+	async refreshToken(): Promise<SeaTalkTokenInfo> {
+		if (this.tokenPromise) {
+			return this.tokenPromise;
+		}
+
+		this.tokenPromise = this._fetchToken();
+		try {
+			const info = await this.tokenPromise;
+			this.tokenInfo = info;
+			return info;
+		} finally {
+			this.tokenPromise = null;
+		}
+	}
+
+	private async _fetchToken(): Promise<SeaTalkTokenInfo> {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
+
+		try {
+			const res = await fetch(`${BASE_URL}/auth/app_access_token`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({
+					app_id: this.appId,
+					app_secret: this.appSecret,
+				}),
+				signal: controller.signal,
+			});
+
+			if (!res.ok) {
+				const xRid = res.headers.get("x-rid") ?? undefined;
+				throw new Error(
+					`SeaTalk token request failed: HTTP ${res.status} (x-rid: ${xRid})`,
+				);
+			}
+
+			const data = (await res.json()) as {
+				code: number;
+				app_access_token?: string;
+				expire?: number;
+				message?: string;
+			};
+
+			if (data.code !== 0) {
+				throw new Error(
+					`SeaTalk token error: code=${data.code} message=${data.message ?? "unknown"}`,
+				);
+			}
+
+			if (!data.app_access_token || !data.expire) {
+				throw new Error("SeaTalk token response missing token or expire");
+			}
+
+			return {
+				token: data.app_access_token,
+				expireAt: data.expire,
+			};
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+
+	async apiCall<T = Record<string, unknown>>(
+		method: string,
+		path: string,
+		body?: unknown,
+		retry = true,
+	): Promise<T> {
+		const token = await this.getAccessToken();
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
+
+		try {
+			const res = await fetch(`${BASE_URL}${path}`, {
+				method,
+				headers: {
+					Authorization: `Bearer ${token}`,
+					"Content-Type": "application/json",
+				},
+				body: body ? JSON.stringify(body) : undefined,
+				signal: controller.signal,
+			});
+
+			const xRid = res.headers.get("x-rid") ?? undefined;
+
+			if (!res.ok) {
+				throw Object.assign(
+					new Error(`SeaTalk API error: HTTP ${res.status} (x-rid: ${xRid})`),
+					{ httpStatus: res.status, xRid },
+				);
+			}
+
+			const data = (await res.json()) as { code: number; message?: string } & T;
+
+			if (data.code === 100 && retry) {
+				await this.refreshToken();
+				return this.apiCall<T>(method, path, body, false);
+			}
+
+			if (data.code === 101) {
+				throw Object.assign(new Error("SeaTalk rate limit exceeded"), {
+					code: 101,
+					xRid,
+				});
+			}
+
+			if (data.code !== 0) {
+				throw Object.assign(
+					new Error(
+						`SeaTalk API error: code=${data.code} message=${data.message ?? "unknown"} (x-rid: ${xRid})`,
+					),
+					{ code: data.code, xRid },
+				);
+			}
+
+			return data;
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+
+	async sendSingleChat(
+		employeeCode: string,
+		message: Record<string, unknown>,
+		threadId?: string,
+	): Promise<void> {
+		const msg = threadId ? { ...message, thread_id: threadId } : message;
+		await this.apiCall("POST", "/messaging/v2/single_chat", {
+			employee_code: employeeCode,
+			message: msg,
+		});
+	}
+
+	async sendGroupChat(
+		groupId: string,
+		message: Record<string, unknown>,
+		threadId?: string,
+	): Promise<void> {
+		const msg = threadId ? { ...message, thread_id: threadId } : message;
+		await this.apiCall("POST", "/messaging/v2/group_chat", {
+			group_id: groupId,
+			message: msg,
+		});
+	}
+
+	async setSingleChatTyping(employeeCode: string, threadId?: string): Promise<void> {
+		const body: Record<string, string> = { employee_code: employeeCode };
+		if (threadId) body.thread_id = threadId;
+		await this.apiCall("POST", "/messaging/v2/single_chat_typing", body);
+	}
+
+	async setGroupChatTyping(groupId: string, threadId?: string): Promise<void> {
+		const body: Record<string, string> = { group_id: groupId };
+		if (threadId) body.thread_id = threadId;
+		await this.apiCall("POST", "/messaging/v2/group_chat_typing", body);
+	}
+
+	async downloadMedia(url: string): Promise<{ buffer: Buffer; contentType: string }> {
+		const token = await this.getAccessToken();
+
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 60_000);
+
+		try {
+			const res = await fetch(url, {
+				headers: { Authorization: `Bearer ${token}` },
+				signal: controller.signal,
+			});
+
+			if (!res.ok) {
+				throw new Error(`SeaTalk media download failed: HTTP ${res.status}`);
+			}
+
+			const contentType = res.headers.get("content-type") ?? "application/octet-stream";
+			const arrayBuffer = await res.arrayBuffer();
+			return {
+				buffer: Buffer.from(arrayBuffer),
+				contentType,
+			};
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+
+	async getEmployeeCodeByEmail(
+		emails: string[],
+	): Promise<Array<{ email: string; employeeCode: string | null; status: number }>> {
+		const BATCH_LIMIT = 500;
+		const results: Array<{ email: string; employeeCode: string | null; status: number }> = [];
+
+		for (let i = 0; i < emails.length; i += BATCH_LIMIT) {
+			const batch = emails.slice(i, i + BATCH_LIMIT);
+			const data = await this.apiCall<{
+				employees: Array<{
+					code: number;
+					email: string;
+					employee_code: string | null;
+					employee_status: number;
+				}>;
+			}>("POST", "/contacts/v2/get_employee_code_with_email", { emails: batch });
+
+			for (const e of data.employees ?? []) {
+				results.push({
+					email: e.email,
+					employeeCode: e.employee_code,
+					status: e.employee_status,
+				});
+			}
+		}
+
+		return results;
+	}
+
+	async getGroupChatHistory(
+		groupId: string,
+		opts?: { pageSize?: number; cursor?: string },
+	): Promise<Record<string, unknown>> {
+		const params = new URLSearchParams({
+			group_id: groupId,
+			page_size: String(opts?.pageSize ?? 50),
+		});
+		if (opts?.cursor) params.set("cursor", opts.cursor);
+		return this.apiCall("GET", `/messaging/v2/group_chat/history?${params}`);
+	}
+
+	async getJoinedGroupChats(opts?: { pageSize?: number; cursor?: string }): Promise<
+		Record<string, unknown>
+	> {
+		const params = new URLSearchParams();
+		if (opts?.pageSize) params.set("page_size", String(opts.pageSize));
+		if (opts?.cursor) params.set("cursor", opts.cursor);
+		const qs = params.toString();
+		return this.apiCall("GET", `/messaging/v2/group_chat/joined${qs ? `?${qs}` : ""}`);
+	}
+
+	async getGroupChatInfo(groupId: string): Promise<Record<string, unknown>> {
+		return this.apiCall(
+			"GET",
+			`/messaging/v2/group_chat/info?group_id=${encodeURIComponent(groupId)}`,
+		);
+	}
+
+	async getDmThread(
+		employeeCode: string,
+		threadId: string,
+		opts?: { pageSize?: number; cursor?: string },
+	): Promise<Record<string, unknown>> {
+		const params = new URLSearchParams({
+			employee_code: employeeCode,
+			thread_id: threadId,
+		});
+		if (opts?.pageSize) params.set("page_size", String(opts.pageSize));
+		if (opts?.cursor) params.set("cursor", opts.cursor);
+		return this.apiCall("GET", `/messaging/v2/single_chat/get_thread_by_thread_id?${params}`);
+	}
+
+	async getGroupThread(
+		groupId: string,
+		threadId: string,
+		opts?: { pageSize?: number; cursor?: string },
+	): Promise<Record<string, unknown>> {
+		const params = new URLSearchParams({
+			group_id: groupId,
+			thread_id: threadId,
+		});
+		if (opts?.pageSize) params.set("page_size", String(opts.pageSize));
+		if (opts?.cursor) params.set("cursor", opts.cursor);
+		return this.apiCall("GET", `/messaging/v2/group_chat/get_thread_by_thread_id?${params}`);
+	}
+
+	async getMessageByMessageId(messageId: string): Promise<Record<string, unknown>> {
+		return this.apiCall(
+			"GET",
+			`/messaging/v2/get_message_by_message_id?message_id=${encodeURIComponent(messageId)}`,
+		);
+	}
+
+	getAppId(): string {
+		return this.appId;
+	}
+}
+
+const clientCache = new Map<string, SeaTalkClient>();
+
+export function getSeaTalkClient(appId: string, appSecret: string): SeaTalkClient {
+	const key = `${appId}:${appSecret}`;
+	let client = clientCache.get(key);
+	if (!client) {
+		client = new SeaTalkClient(appId, appSecret);
+		clientCache.set(key, client);
+	}
+	return client;
+}
+
+export function resolveSeaTalkClient(params: {
+	appId?: string;
+	appSecret?: string;
+}): SeaTalkClient | null {
+	if (!params.appId || !params.appSecret) return null;
+	return getSeaTalkClient(params.appId, params.appSecret);
+}