whatsappd 0.1.0

package/dist/sidecar/index.mjs

@@ -0,0 +1,326 @@
+import { a as createSession, i as qrAuth, n as fileStore, r as pairingAuth, t as createChannelAdapter } from "../adapter-BES4PRA9.mjs";
+import { i as toWireUpdate, n as reviveOutbound, r as toWireMessage, t as messagePreview } from "../wire-CsVVkLhn.mjs";
+import pino from "pino";
+import { pathToFileURL } from "node:url";
+import qrcode from "qrcode-terminal";
+import { createServer } from "node:http";
+//#region src/sidecar/server.ts
+/**
+* Sidecar HTTP server — wraps one account's {@link WhatsAppChannelAdapter}
+* behind a plain HTTP surface so framework adapters (Eve, or any HTTP client)
+* never touch the WhatsApp socket. One sidecar process = one WhatsApp account;
+* run more processes for more numbers (they can all forward into the same app —
+* events carry `accountId` so the receiver can tell them apart):
+*
+*   POST /send       { accountId, chatId, content, opts? }  → { ref }
+*   POST /markRead   { accountId, chatId }                  → { ok }
+*   POST /setTyping  { accountId, chatId, kind? }           → { ok }
+*   GET  /media/:accountId/:messageId                       → decrypted bytes
+*   GET  /health                                            → { ok, accounts }
+*
+* Inbound WhatsApp events are pushed the other way: the server subscribes to
+* the adapter and POSTs each event (as a `SidecarEvent`) to the configured
+* forward targets. Media bytes never travel in events — messages carry a
+* `/media/...` URL and the consumer pulls bytes on demand (the handles are
+* kept in a bounded in-memory cache).
+*
+* All routes (and forwarded events) carry `Authorization: Bearer <token>`
+* when a token is configured.
+*/
+var HttpError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+async function readJson(req) {
+	const chunks = [];
+	for await (const chunk of req) chunks.push(chunk);
+	try {
+		return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+	} catch {
+		throw new HttpError(400, "invalid JSON body");
+	}
+}
+function sendJson(res, status, body) {
+	const data = JSON.stringify(body);
+	res.writeHead(status, { "content-type": "application/json" });
+	res.end(data);
+}
+function createSidecarServer(options) {
+	const log = options.logger;
+	const fetchFn = options.fetchFn ?? fetch;
+	const forward = options.forward ?? [];
+	const mediaCapacity = options.mediaCacheSize ?? 512;
+	const adapter = options.adapter;
+	const media = /* @__PURE__ */ new Map();
+	function cacheMedia(key, handle) {
+		media.set(key, handle);
+		while (media.size > mediaCapacity) {
+			const oldest = media.keys().next().value;
+			if (oldest === void 0) break;
+			media.delete(oldest);
+		}
+	}
+	/**
+	* A misaddressed request is a routing bug on the caller's side (e.g. an app
+	* serving several sidecars replying to the wrong one) — 404 it rather than
+	* silently delivering through the wrong account.
+	*/
+	function requireAccount(accountId) {
+		if (typeof accountId !== "string" || accountId.length === 0) throw new HttpError(400, "accountId is required");
+		if (accountId !== adapter.accountId) throw new HttpError(404, `unknown account ${accountId}`);
+		return adapter;
+	}
+	async function forwardEvent(event) {
+		await Promise.all(forward.map(async (target) => {
+			try {
+				const res = await fetchFn(target.url, {
+					method: "POST",
+					headers: {
+						"content-type": "application/json",
+						...target.token && { authorization: `Bearer ${target.token}` }
+					},
+					body: JSON.stringify(event)
+				});
+				if (!res.ok) log?.warn({
+					url: target.url,
+					status: res.status
+				}, "event forward failed");
+			} catch (err) {
+				log?.warn({
+					url: target.url,
+					err
+				}, "event forward failed");
+			}
+		}));
+	}
+	function toSidecarEvent(accountId, event) {
+		switch (event.type) {
+			case "message": {
+				if (event.message.fromMe) return void 0;
+				let mediaUrl;
+				if ("media" in event.message) {
+					const path = `/media/${encodeURIComponent(accountId)}/${encodeURIComponent(event.message.id)}`;
+					cacheMedia(`${accountId}/${event.message.id}`, event.message.media);
+					mediaUrl = options.baseUrl ? new URL(path, options.baseUrl).href : path;
+				}
+				return {
+					type: "message",
+					accountId,
+					chatId: event.ref.chatId,
+					isGroup: event.ref.isGroup,
+					from: event.ref.from,
+					pushName: event.ref.pushName,
+					message: toWireMessage(event.message, mediaUrl)
+				};
+			}
+			case "update": return {
+				type: "update",
+				accountId,
+				chatId: event.ref.chatId,
+				update: toWireUpdate(event.update)
+			};
+			case "status": return {
+				type: "status",
+				accountId,
+				status: event.status
+			};
+		}
+	}
+	const unsubscribe = adapter.subscribe({ async onEvent(event) {
+		const wire = toSidecarEvent(adapter.accountId, event);
+		if (wire) await forwardEvent(wire);
+	} });
+	async function route(req, res) {
+		if (options.token && req.headers.authorization !== `Bearer ${options.token}`) throw new HttpError(401, "unauthorized");
+		const url = new URL(req.url ?? "/", "http://sidecar");
+		const key = `${req.method} ${url.pathname}`;
+		if (key === "GET /health") {
+			sendJson(res, 200, {
+				ok: true,
+				accounts: [adapter.accountId]
+			});
+			return;
+		}
+		if (key === "POST /send") {
+			const body = await readJson(req);
+			sendJson(res, 200, { ref: await requireAccount(body.accountId).send(body.chatId, reviveOutbound(body.content), body.opts) });
+			return;
+		}
+		if (key === "POST /markRead") {
+			const body = await readJson(req);
+			await requireAccount(body.accountId).markRead(body.chatId);
+			sendJson(res, 200, { ok: true });
+			return;
+		}
+		if (key === "POST /setTyping") {
+			const body = await readJson(req);
+			await requireAccount(body.accountId).setTyping(body.chatId, body.kind ?? "typing");
+			sendJson(res, 200, { ok: true });
+			return;
+		}
+		const mediaMatch = /^\/media\/([^/]+)\/([^/]+)$/.exec(url.pathname);
+		if (req.method === "GET" && mediaMatch) {
+			const cacheKey = `${decodeURIComponent(mediaMatch[1])}/${decodeURIComponent(mediaMatch[2])}`;
+			const handle = media.get(cacheKey);
+			if (!handle) throw new HttpError(404, "media not available (expired from cache?)");
+			const bytes = await handle.download();
+			res.writeHead(200, {
+				"content-type": handle.mimetype ?? "application/octet-stream",
+				"content-length": bytes.length
+			});
+			res.end(bytes);
+			return;
+		}
+		throw new HttpError(404, `no route for ${key}`);
+	}
+	const server = createServer((req, res) => {
+		route(req, res).catch((err) => {
+			const status = err instanceof HttpError ? err.status : 500;
+			if (status === 500) log?.error({
+				err,
+				url: req.url
+			}, "sidecar request failed");
+			const message = err instanceof Error ? err.message : "internal error";
+			if (!res.headersSent) sendJson(res, status, { error: message });
+			else res.end();
+		});
+	});
+	return {
+		server,
+		listen(port, host = "0.0.0.0") {
+			return new Promise((resolve, reject) => {
+				server.once("error", reject);
+				server.listen(port, host, () => {
+					const address = server.address();
+					const boundPort = typeof address === "object" && address ? address.port : port;
+					log?.info({ port: boundPort }, "sidecar listening");
+					resolve({ port: boundPort });
+				});
+			});
+		},
+		close() {
+			unsubscribe();
+			return new Promise((resolve, reject) => {
+				server.close((err) => err ? reject(err) : resolve());
+			});
+		}
+	};
+}
+//#endregion
+//#region src/sidecar/index.ts
+/**
+* Sidecar entry point — boots one WhatsApp session, its channel adapter, and
+* the HTTP server. One sidecar process = one WhatsApp account; run more
+* processes for more numbers. Run it standalone:
+*
+*   WHATSAPP_FORWARD_URLS=... node --experimental-strip-types src/sidecar/index.ts
+*
+* Environment:
+*   PORT                    HTTP port (default 8788)
+*   HOST                    bind host (default 0.0.0.0)
+*   WHATSAPP_ACCOUNT        account label on events/requests (default "default")
+*   WHATSAPP_STORE_DIR      credential store directory (default ./.wa-auth)
+*   WHATSAPP_PAIRING_PHONE  E.164 phone for pairing-code login (default: QR)
+*   WHATSAPP_FORWARD_URLS   comma-separated framework endpoints inbound
+*                           events are POSTed to (e.g. the Eve channel's
+*                           https://app.example.com/api/channels/whatsapp/event)
+*   WHATSAPP_SIDECAR_TOKEN  shared bearer token, both directions
+*   WHATSAPP_BASE_URL       this sidecar's public URL, used to build
+*                           absolute media URLs in events
+*   LOG_LEVEL               pino level (default info)
+*
+* First run prints a QR (or pairing code) — link it in WhatsApp → Linked
+* devices. Credentials persist in WHATSAPP_STORE_DIR, so restarts reconnect
+* silently.
+*/
+function pairingLogger(accountId, log) {
+	return (event) => {
+		if (event.type !== "status") return;
+		const status = event.status;
+		switch (status.phase) {
+			case "pairing":
+				if (status.pairing.step === "challenge_live") {
+					if (status.pairing.qr) {
+						log.info({ accountId }, "scan this QR in WhatsApp → Linked devices");
+						qrcode.generate(status.pairing.qr, { small: true });
+					} else if (status.pairing.code) log.info({
+						accountId,
+						code: status.pairing.code
+					}, "enter this pairing code");
+				}
+				break;
+			case "online":
+				log.info({ accountId }, "online — sendable");
+				break;
+			case "logged_out":
+			case "suspended":
+				log.error({
+					accountId,
+					reason: status.reason
+				}, `terminal: ${status.phase}`);
+				break;
+			default: log.debug({
+				accountId,
+				phase: status.phase
+			}, "status");
+		}
+	};
+}
+async function runSidecar(env = process.env) {
+	const accountId = env.WHATSAPP_ACCOUNT ?? "default";
+	const storeDir = env.WHATSAPP_STORE_DIR ?? "./.wa-auth";
+	const token = env.WHATSAPP_SIDECAR_TOKEN;
+	const phone = env.WHATSAPP_PAIRING_PHONE;
+	const forward = (env.WHATSAPP_FORWARD_URLS ?? "").split(",").map((s) => s.trim()).filter(Boolean).map((url) => ({
+		url,
+		token
+	}));
+	const logger = pino({
+		level: env.LOG_LEVEL ?? "info",
+		transport: {
+			target: "pino-pretty",
+			options: { colorize: true }
+		}
+	});
+	const adapter = createChannelAdapter({
+		session: createSession({
+			store: fileStore(storeDir),
+			auth: phone ? pairingAuth(phone) : qrAuth(),
+			logger
+		}),
+		accountId,
+		logger
+	});
+	adapter.subscribe({ onEvent: pairingLogger(accountId, logger) });
+	const server = createSidecarServer({
+		adapter,
+		forward,
+		token,
+		baseUrl: env.WHATSAPP_BASE_URL,
+		logger
+	});
+	await adapter.start();
+	const { port } = await server.listen(Number(env.PORT ?? 8788), env.HOST);
+	logger.info({
+		port,
+		accountId,
+		forward: forward.map((f) => f.url)
+	}, "sidecar up");
+	return {
+		port,
+		server,
+		async close() {
+			await server.close();
+			await adapter.stop();
+		}
+	};
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) runSidecar().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});
+//#endregion
+export { createSidecarServer, messagePreview, reviveOutbound, runSidecar, toWireMessage, toWireUpdate };

package/dist/stores/libsql.d.mts

@@ -0,0 +1,16 @@
+import { n as SessionStore } from "../ports-DeTIMztA.mjs";
+
+//#region src/stores/libsql.d.ts
+interface LibsqlStoreOptions {
+  /** `file:wa-auth.db` for local, or a `libsql://…turso.io` URL for remote. */
+  url: string;
+  /** Auth token for a remote Turso database. */
+  authToken?: string;
+  /** Namespace — one row-space per account. Default `"default"`. */
+  account?: string;
+  /** Table name. Default `"wa_auth"`. */
+  table?: string;
+}
+declare function libsqlStore(options: LibsqlStoreOptions): SessionStore;
+//#endregion
+export { LibsqlStoreOptions, libsqlStore };

package/dist/stores/libsql.mjs

@@ -0,0 +1,57 @@
+//#region src/stores/libsql.ts
+/** Validate the table name ourselves — it's interpolated, never parameterizable. */
+function safeTable(name) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`libsqlStore: invalid table name ${JSON.stringify(name)}`);
+	return name;
+}
+function libsqlStore(options) {
+	const account = options.account ?? "default";
+	const table = safeTable(options.table ?? "wa_auth");
+	let ready;
+	const connect = () => ready ??= (async () => {
+		let createClient;
+		try {
+			({createClient} = await import("@libsql/client"));
+		} catch {
+			throw new Error("libsqlStore requires the optional peer dependency '@libsql/client'. Install it: npm i @libsql/client");
+		}
+		const client = createClient({
+			url: options.url,
+			...options.authToken != null && { authToken: options.authToken }
+		});
+		await client.execute(`CREATE TABLE IF NOT EXISTS ${table} (account TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (account, key))`);
+		return client;
+	})();
+	return {
+		async read(key) {
+			const value = (await (await connect()).execute({
+				sql: `SELECT value FROM ${table} WHERE account = ? AND key = ?`,
+				args: [account, key]
+			})).rows[0]?.value;
+			return value == null ? null : String(value);
+		},
+		async write(entries) {
+			const pairs = Object.entries(entries);
+			if (pairs.length === 0) return;
+			await (await connect()).batch(pairs.map(([key, value]) => value === null ? {
+				sql: `DELETE FROM ${table} WHERE account = ? AND key = ?`,
+				args: [account, key]
+			} : {
+				sql: `INSERT INTO ${table} (account, key, value) VALUES (?, ?, ?) ON CONFLICT(account, key) DO UPDATE SET value = excluded.value`,
+				args: [
+					account,
+					key,
+					value
+				]
+			}), "write");
+		},
+		async clear() {
+			await (await connect()).execute({
+				sql: `DELETE FROM ${table} WHERE account = ?`,
+				args: [account]
+			});
+		}
+	};
+}
+//#endregion
+export { libsqlStore };

package/dist/stores/memory.d.mts

@@ -0,0 +1,6 @@
+import { n as SessionStore } from "../ports-DeTIMztA.mjs";
+
+//#region src/stores/memory.d.ts
+declare function memoryStore(): SessionStore;
+//#endregion
+export { memoryStore };

package/dist/stores/memory.mjs

@@ -0,0 +1,18 @@
+//#region src/stores/memory.ts
+function memoryStore() {
+	const map = /* @__PURE__ */ new Map();
+	return {
+		async read(key) {
+			return map.get(key) ?? null;
+		},
+		async write(entries) {
+			for (const [key, value] of Object.entries(entries)) if (value === null) map.delete(key);
+			else map.set(key, value);
+		},
+		async clear() {
+			map.clear();
+		}
+	};
+}
+//#endregion
+export { memoryStore };

package/dist/tools/index.d.mts

@@ -0,0 +1,99 @@
+import { b as BinaryInput, v as PresenceKind, x as MessageRef } from "../update-Bi5ZPUjP.mjs";
+import { i as WhatsAppChannelAdapter } from "../types-B8d1OyHV.mjs";
+
+//#region src/tools/index.d.ts
+/** Media kinds that `sendMedia` accepts. */
+type MediaKind = "image" | "video" | "audio" | "document" | "sticker";
+/**
+ * Per-call context injected by the framework adapter.
+ *
+ * @remarks
+ * `chatId` is the conversation the agent is currently responding in, and
+ * `adapter` is the channel adapter for the account handling that conversation.
+ */
+interface ToolContext {
+  readonly chatId: string;
+  readonly adapter: WhatsAppChannelAdapter;
+}
+/**
+ * A generic agent tool: a stable `name`, an LLM-facing `description`, and a
+ * typed `call`.
+ *
+ * @typeParam I - The tool's input shape.
+ * @typeParam O - The tool's result shape.
+ */
+interface AgentTool<I = Record<string, unknown>, O = unknown> {
+  /** Unique, namespaced tool name (e.g. `"whatsapp.sendText"`). */
+  readonly name: string;
+  /** Human-readable description surfaced to the model. */
+  readonly description: string;
+  /**
+   * Execute the tool.
+   *
+   * @param input - The tool's typed input.
+   * @param ctx - The per-call {@link ToolContext}.
+   * @returns The tool's result.
+   */
+  call(input: I, ctx: ToolContext): Promise<O>;
+}
+interface SendTextInput {
+  text: string;
+}
+declare const sendText: AgentTool<SendTextInput, MessageRef>;
+interface SendMediaInput {
+  kind: MediaKind;
+  media: BinaryInput;
+  caption?: string;
+  /** audio: send as a push-to-talk voice note. */
+  ptt?: boolean;
+  /** audio: duration in seconds. */
+  seconds?: number;
+  /** audio/document: override mimetype. */
+  mimetype?: string;
+  /** document: filename (required for documents). */
+  fileName?: string;
+  /** video: play silently like a GIF. */
+  gifPlayback?: boolean;
+}
+declare const sendMedia: AgentTool<SendMediaInput, MessageRef>;
+interface ReplyInput {
+  text: string;
+  quote: MessageRef;
+}
+declare const reply: AgentTool<ReplyInput, MessageRef>;
+declare const markRead: AgentTool<void, void>;
+interface SetTypingInput {
+  kind?: PresenceKind;
+}
+declare const setTyping: AgentTool<SetTypingInput, void>;
+interface ReactInput {
+  emoji: string;
+  ref: MessageRef;
+}
+declare const react: AgentTool<ReactInput, MessageRef>;
+interface EditInput {
+  text: string;
+  ref: MessageRef;
+}
+declare const edit: AgentTool<EditInput, MessageRef>;
+interface DeleteInput {
+  ref: MessageRef;
+}
+declare const deleteMsg: AgentTool<DeleteInput, MessageRef>;
+/** All eight tools, in a fixed order. */
+declare const allTools: AgentTool<any, any>[];
+/**
+ * Get the full set of tools for a conversation.
+ *
+ * @remarks
+ * Because each tool receives its {@link ToolContext} at call time, this
+ * currently returns {@link allTools} unchanged. It exists as the stable entry
+ * point a framework adapter calls once per conversation (or per session) to
+ * obtain the tool array for its agent.
+ *
+ * @param _ctx - The conversation context (reserved for future per-context binding).
+ * @returns The eight agent tools.
+ */
+declare function bindTools(_ctx: ToolContext): AgentTool<any, any>[];
+//#endregion
+export { AgentTool, DeleteInput, EditInput, MediaKind, ReactInput, ReplyInput, SendMediaInput, SendTextInput, SetTypingInput, ToolContext, allTools, bindTools, deleteMsg, edit, markRead, react, reply, sendMedia, sendText, setTyping };

package/dist/tools/index.mjs

@@ -0,0 +1,117 @@
+//#region src/tools/index.ts
+const sendText = {
+	name: "whatsapp.sendText",
+	description: "Send a text message to the current WhatsApp conversation.",
+	async call({ text }, ctx) {
+		return ctx.adapter.send(ctx.chatId, { text });
+	}
+};
+function mediaOutbound(input) {
+	switch (input.kind) {
+		case "image": return {
+			image: input.media,
+			caption: input.caption
+		};
+		case "video": return {
+			video: input.media,
+			caption: input.caption,
+			gifPlayback: input.gifPlayback
+		};
+		case "audio": return {
+			audio: input.media,
+			ptt: input.ptt,
+			seconds: input.seconds,
+			mimetype: input.mimetype
+		};
+		case "document": return {
+			document: input.media,
+			fileName: input.fileName ?? "file",
+			mimetype: input.mimetype ?? "application/octet-stream",
+			caption: input.caption
+		};
+		case "sticker": return { sticker: input.media };
+	}
+}
+const sendMedia = {
+	name: "whatsapp.sendMedia",
+	description: "Send an image, video, audio, document, or sticker to the current conversation. Provide `media` as a Buffer, { url }, or { stream }. Documents require `fileName`.",
+	async call(input, ctx) {
+		return ctx.adapter.send(ctx.chatId, mediaOutbound(input));
+	}
+};
+const reply = {
+	name: "whatsapp.reply",
+	description: "Reply to a specific message by quoting it.",
+	async call({ text, quote }, ctx) {
+		return ctx.adapter.send(ctx.chatId, { text }, { quote });
+	}
+};
+const markRead = {
+	name: "whatsapp.markRead",
+	description: "Mark the current conversation as read (blue ticks).",
+	async call(_input, ctx) {
+		await ctx.adapter.markRead(ctx.chatId);
+	}
+};
+const setTyping = {
+	name: "whatsapp.setTyping",
+	description: "Set typing or recording presence in the current conversation. Defaults to 'typing'; pass 'recording' for voice-note mode.",
+	async call({ kind = "typing" }, ctx) {
+		await ctx.adapter.setTyping(ctx.chatId, kind);
+	}
+};
+const react = {
+	name: "whatsapp.react",
+	description: "React to a message with an emoji. Pass empty string to clear.",
+	async call({ emoji, ref }, ctx) {
+		return ctx.adapter.send(ctx.chatId, { react: {
+			to: ref,
+			emoji
+		} });
+	}
+};
+const edit = {
+	name: "whatsapp.edit",
+	description: "Edit a previously sent message.",
+	async call({ text, ref }, ctx) {
+		return ctx.adapter.send(ctx.chatId, { edit: {
+			target: ref,
+			text
+		} });
+	}
+};
+const deleteMsg = {
+	name: "whatsapp.delete",
+	description: "Delete a message (revoke for everyone).",
+	async call({ ref }, ctx) {
+		return ctx.adapter.send(ctx.chatId, { delete: ref });
+	}
+};
+/** All eight tools, in a fixed order. */
+const allTools = [
+	sendText,
+	sendMedia,
+	reply,
+	markRead,
+	setTyping,
+	react,
+	edit,
+	deleteMsg
+];
+/**
+* Get the full set of tools for a conversation.
+*
+* @remarks
+* Because each tool receives its {@link ToolContext} at call time, this
+* currently returns {@link allTools} unchanged. It exists as the stable entry
+* point a framework adapter calls once per conversation (or per session) to
+* obtain the tool array for its agent.
+*
+* @param _ctx - The conversation context (reserved for future per-context binding).
+* @returns The eight agent tools.
+*/
+function bindTools(_ctx) {
+	return allTools;
+}
+//#endregion
+export { allTools, bindTools, deleteMsg, edit, markRead, react, reply, sendMedia, sendText, setTyping };