adapter.py 39 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724
  1. """BlueBubbles iMessage platform adapter: local BlueBubbles macOS server for outbound REST sends and
  2. inbound webhooks (text, media attachments, typing indicators, read receipts)."""
  3. import asyncio
  4. import json
  5. import logging
  6. import os
  7. import re
  8. import uuid
  9. from collections import OrderedDict
  10. from contextlib import suppress
  11. from datetime import datetime
  12. from pathlib import Path
  13. from typing import Any, Dict, List, Optional
  14. from urllib.parse import parse_qs, quote
  15. import httpx
  16. from gateway.config import Platform, PlatformConfig
  17. from gateway.platforms._shared import extra_or_secret as _extra_or_secret, get_scoped_secret as _get_scoped_secret
  18. from gateway.platforms._shared import config_connected_extra
  19. from gateway.platforms.base import (
  20. BasePlatformAdapter, SendResult,
  21. cache_image_from_bytes_async, cache_audio_from_bytes_async, cache_document_from_bytes_async,
  22. )
  23. from gateway.platforms.event import MessageEvent, MessageType
  24. from gateway.platforms.media_cache import ext_for_mime
  25. from gateway.platforms.helpers import compile_mention_patterns, strip_markdown
  26. from utils import TRUTHY_STRINGS
  27. # Historical BlueBubbles mime→ext maps, preserved verbatim as overrides for the shared dispatch in
  28. # gateway.platforms.media_cache. Both maps are CLOSED: unlisted mimes fall back to .jpg / .mp3.
  29. _BLUEBUBBLES_IMAGE_EXT_OVERRIDES = {
  30. "image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif", "image/webp": ".webp",
  31. "image/heic": ".jpg", "image/heif": ".jpg", "image/tiff": ".jpg", # historical mapping
  32. }
  33. _BLUEBUBBLES_AUDIO_EXT_OVERRIDES = {
  34. "audio/mp3": ".mp3", "audio/mpeg": ".mp3", "audio/ogg": ".ogg", "audio/wav": ".wav",
  35. "audio/x-caf": ".mp3", "audio/mp4": ".m4a",
  36. "audio/aac": ".m4a", # historical mapping (shared table says .aac)
  37. }
  38. logger = logging.getLogger(__name__)
  39. DEFAULT_WEBHOOK_HOST = "127.0.0.1"
  40. # Webhook events are small JSON/form payloads (attachments come through the REST API); 1 MiB keeps
  41. # oversized/chunked bodies from buffering unbounded.
  42. _WEBHOOK_MAX_BODY_BYTES = 1_048_576
  43. DEFAULT_WEBHOOK_PORT = 8645
  44. DEFAULT_WEBHOOK_PATH = "/bluebubbles-webhook"
  45. MAX_TEXT_LENGTH = 4000
  46. # iMessage has no stable bot mention identity (unlike <@U...>/@botname/MXID), so
  47. # `require_mention: true` without custom aliases uses Hermes wake words.
  48. DEFAULT_MENTION_PATTERNS = [r"(?<![\w@])@?hermes\s+agent\b[,:\-]?", r"(?<![\w@])@?hermes\b[,:\-]?"]
  49. # Tapback associatedMessageType codes: 2000-2005 added, 3000-3005 removed (love, like, dislike, ...).
  50. _TAPBACK_CODES = {*range(2000, 2006), *range(3000, 3006)}
  51. _MESSAGE_EVENTS = {"new-message", "message", "updated-message"} # webhook event types carrying user messages
  52. _PHONE_RE = re.compile(r"\+?\d{7,15}")
  53. _EMAIL_RE = re.compile(r"[\w.+-]+@[\w-]+\.[\w.]+")
  54. _PAGINATION_SUFFIX_RE = re.compile(r"\s*\(\d+/\d+\)$")
  55. _ADDRESS_RE = re.compile(r"^\+\d+")
  56. _GUID_CACHE_SIZE = 500 # LRU cap for resolved chat-GUID lookups
  57. _LOCAL_HOSTS = {"0.0.0.0", "127.0.0.1", "localhost", "::"}
  58. def _redact(text: str) -> str:
  59. """Redact phone numbers and emails from log output."""
  60. return _EMAIL_RE.sub("[REDACTED]", _PHONE_RE.sub("[REDACTED]", text))
  61. def check_bluebubbles_requirements() -> bool:
  62. try:
  63. import aiohttp
  64. except ImportError:
  65. return False
  66. return True
  67. def _normalize_server_url(raw: str) -> str:
  68. value = (raw or "").strip()
  69. if value and not re.match(r"^https?://", value, flags=re.IGNORECASE):
  70. value = f"http://{value}"
  71. return value.rstrip("/")
  72. def _closed_ext(mime: str, overrides: dict[str, str], fallback: str) -> str:
  73. """Historical maps were closed: unlisted mimes fall back without consulting mimetypes."""
  74. return ext_for_mime(mime, overrides=overrides, use_defaults=False, use_mimetypes=False,
  75. fallback=fallback) or fallback
  76. def _temp_guid() -> str:
  77. return f"temp-{datetime.utcnow().timestamp()}"
  78. def _ok():
  79. """Plain ``ok`` acknowledgement for webhook events we accept but don't process."""
  80. from aiohttp import web
  81. return web.Response(text="ok")
  82. class BlueBubblesAdapter(BasePlatformAdapter):
  83. # Answers /p/<profile>/... on the default listener for a served secondary (shared_ingress).
  84. serves_profile_prefix: bool = True
  85. platform = Platform.BLUEBUBBLES
  86. SUPPORTS_MESSAGE_EDITING = False
  87. MAX_MESSAGE_LENGTH = MAX_TEXT_LENGTH
  88. splits_long_messages = True # send() chunks via truncate_message(MAX_MESSAGE_LENGTH)
  89. def __init__(self, config: PlatformConfig):
  90. super().__init__(config, Platform.BLUEBUBBLES)
  91. extra = config.extra or {}
  92. self.server_url = _normalize_server_url(_extra_or_secret(extra, "server_url", "BLUEBUBBLES_SERVER_URL"))
  93. self.password = extra.get("password") or _get_scoped_secret("BLUEBUBBLES_PASSWORD", "")
  94. self.webhook_host = _extra_or_secret(extra, "webhook_host", "BLUEBUBBLES_WEBHOOK_HOST", DEFAULT_WEBHOOK_HOST)
  95. self.webhook_port = int(_extra_or_secret(extra, "webhook_port", "BLUEBUBBLES_WEBHOOK_PORT", str(DEFAULT_WEBHOOK_PORT)))
  96. path = str(_extra_or_secret(extra, "webhook_path", "BLUEBUBBLES_WEBHOOK_PATH", DEFAULT_WEBHOOK_PATH))
  97. self.webhook_path = path if path.startswith("/") else f"/{path}"
  98. self.send_read_receipts = bool(extra.get("send_read_receipts", True))
  99. _require_mention = extra.get("require_mention")
  100. if _require_mention is None:
  101. _require_mention = _get_scoped_secret("BLUEBUBBLES_REQUIRE_MENTION")
  102. self.require_mention = str(_require_mention).strip().lower() in TRUTHY_STRINGS
  103. self._mention_patterns = self._compile_mention_patterns(
  104. extra["mention_patterns"] if "mention_patterns" in extra else _get_scoped_secret("BLUEBUBBLES_MENTION_PATTERNS"))
  105. self.client: Optional[httpx.AsyncClient] = None
  106. self._runner = None
  107. self._private_api_enabled: Optional[bool] = None
  108. self._helper_connected: bool = False
  109. self._guid_cache: OrderedDict[str, str] = OrderedDict()
  110. # --- API helpers ---
  111. def _api_url(self, path: str) -> str:
  112. return f"{self.server_url}{path}{'&' if '?' in path else '?'}password={quote(self.password, safe='')}"
  113. @staticmethod
  114. def _compile_mention_patterns(raw: Any) -> list[re.Pattern]:
  115. """Compile group-mention wake words; ``raw`` is a list, a raw env string (JSON list or
  116. comma/newline-separated), or None (Hermes defaults)."""
  117. return compile_mention_patterns(raw, log_prefix="bluebubbles", defaults=DEFAULT_MENTION_PATTERNS,
  118. logger_=logger)
  119. def _message_matches_mention_patterns(self, text: str) -> bool:
  120. return bool(text) and any(pattern.search(text) for pattern in self._mention_patterns)
  121. def _clean_mention_text(self, text: str) -> str:
  122. """Strip a leading wake word only — patterns are regexes, so stripping anywhere later in the
  123. prompt could delete ordinary words."""
  124. stripped = (text or "").lstrip()
  125. for pattern in self._mention_patterns:
  126. if match := pattern.match(stripped):
  127. return stripped[match.end():].lstrip(" ,:-") or text
  128. return text
  129. async def _api_json(self, method: str, path: str, **kwargs) -> dict[str, Any]:
  130. """Authenticated request to the BlueBubbles REST API; raises on HTTP errors, returns decoded JSON."""
  131. assert self.client is not None
  132. res = await getattr(self.client, method)(self._api_url(path), **kwargs)
  133. res.raise_for_status()
  134. return res.json()
  135. async def _api_get(self, path: str) -> dict[str, Any]:
  136. return await self._api_json("get", path)
  137. async def _api_post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
  138. return await self._api_json("post", path, json=payload)
  139. async def _post_message(self, path: str, payload: dict[str, Any]) -> SendResult:
  140. """POST a message payload and wrap the outcome as a SendResult."""
  141. try:
  142. res = await self._api_post(path, payload)
  143. data = res.get("data") or {}
  144. msg_id = str(data.get("guid") or data.get("messageGuid") or "ok")
  145. return SendResult(success=True, message_id=msg_id, raw_response=res)
  146. except Exception as exc:
  147. return SendResult(success=False, error=str(exc) or type(exc).__name__)
  148. async def _private_api_chat_call(self, chat_id: str, action: str, method: str) -> bool:
  149. """Fire a private-API chat action (typing/read); True only if the call was made."""
  150. if not self._private_api_enabled or not self._helper_connected or not self.client:
  151. return False
  152. with suppress(Exception):
  153. if guid := await self._resolve_chat_guid(chat_id):
  154. url = self._api_url(f"/api/v1/chat/{quote(guid, safe='')}/{action}")
  155. await getattr(self.client, method)(url, timeout=5)
  156. return True
  157. return False
  158. # --- Lifecycle ---
  159. async def connect(self, *, is_reconnect: bool = False) -> bool:
  160. if not self.server_url or not self.password:
  161. logger.error("[bluebubbles] BLUEBUBBLES_SERVER_URL and BLUEBUBBLES_PASSWORD are required")
  162. return False
  163. from aiohttp import web
  164. # Tighter keepalive so idle CLOSE_WAIT drains promptly.
  165. # See #18451.
  166. from gateway.platforms._http_client_limits import platform_httpx_limits
  167. self.client = httpx.AsyncClient(timeout=30.0, limits=platform_httpx_limits())
  168. try:
  169. await self._api_get("/api/v1/ping")
  170. info = await self._api_get("/api/v1/server/info")
  171. server_data = (info or {}).get("data", {})
  172. self._private_api_enabled = bool(server_data.get("private_api"))
  173. self._helper_connected = bool(server_data.get("helper_connected"))
  174. logger.info("[bluebubbles] connected to %s (private_api=%s, helper=%s)",
  175. self.server_url, self._private_api_enabled, self._helper_connected)
  176. except Exception as exc:
  177. logger.error("[bluebubbles] cannot reach server at %s: %s", self.server_url, exc)
  178. await self._close_client()
  179. return False
  180. # client_max_size makes aiohttp enforce the cap on every read path, incl. chunked requests
  181. # with no Content-Length.
  182. # Explicit body cap: BlueBubbles webhook events are small JSON (or form-encoded) payloads.
  183. # client_max_size makes aiohttp enforce the cap on every read path — including chunked requests that
  184. # carry no Content-Length (same pattern as webhook.py / raft, #58536/#58902).
  185. app = web.Application(client_max_size=_WEBHOOK_MAX_BODY_BYTES)
  186. app.router.add_get("/health", lambda _: web.Response(text="ok"))
  187. app.router.add_post(self.webhook_path, self._handle_webhook)
  188. # The webhook auth value rides in the query string (BlueBubbles cannot send custom headers)
  189. # — keep it out of aiohttp access logs.
  190. # Shared-listener mode (multiplex secondary): no bind; served at /p/<profile>/<webhook_path>.
  191. from gateway.platforms.shared_ingress import bind_listener
  192. self._runner = await bind_listener(
  193. self, app, self.webhook_host, self.webhook_port, self.webhook_path, access_log=None)
  194. self._mark_connected()
  195. if self._runner is not None:
  196. logger.info("[bluebubbles] webhook listening on http://%s:%s%s", self.webhook_host, self.webhook_port,
  197. self.webhook_path)
  198. await self._register_webhook() # the server only sends events to webhooks registered via its API
  199. # Plugin-registered native handlers (ctx.register_platform_handler).
  200. self._wire_plugin_handlers(None)
  201. return True
  202. async def _close_client(self) -> None:
  203. if self.client:
  204. await self.client.aclose()
  205. self.client = None
  206. async def disconnect(self) -> None:
  207. await self._unregister_webhook()
  208. await self._close_client()
  209. if self._runner:
  210. await self._runner.cleanup()
  211. self._runner = None
  212. self._mark_disconnected()
  213. @property
  214. def _webhook_url(self) -> str:
  215. """External webhook URL for BlueBubbles registration (local binds → localhost). In
  216. shared-listener mode it is the default listener's ``/p/<profile>/`` URL."""
  217. shared = getattr(self, "_shared_ingress_url", None)
  218. if shared:
  219. return shared
  220. host = "localhost" if self.webhook_host in _LOCAL_HOSTS else self.webhook_host
  221. return f"http://{host}:{self.webhook_port}{self.webhook_path}"
  222. def _webhook_register_url_with(self, password_param: str) -> str:
  223. return f"{self._webhook_url}?password={password_param}" if self.password else self._webhook_url
  224. @property
  225. def _webhook_register_url(self) -> str:
  226. """Registered webhook URL with the password as a query param: BlueBubbles posts to the exact
  227. registered URL and cannot set custom headers, so this is the only way to authenticate inbound
  228. webhooks without disabling auth."""
  229. return self._webhook_register_url_with(quote(self.password, safe=""))
  230. @property
  231. def _webhook_register_url_for_log(self) -> str:
  232. return self._webhook_register_url_with("***")
  233. async def _find_registered_webhooks(self, url: str) -> list:
  234. """Return list of BB webhook entries matching *url*."""
  235. with suppress(Exception):
  236. data = (await self._api_get("/api/v1/webhook")).get("data")
  237. if isinstance(data, list):
  238. return [wh for wh in data if wh.get("url") == url]
  239. return []
  240. async def _register_webhook(self) -> bool:
  241. """Register this webhook URL, reusing an existing registration if present (crash resilience —
  242. avoids duplicates after an unclean shutdown)."""
  243. if not self.client:
  244. return False
  245. webhook_url, log_url = self._webhook_register_url, self._webhook_register_url_for_log
  246. if await self._find_registered_webhooks(webhook_url):
  247. logger.info("[bluebubbles] webhook already registered: %s", log_url)
  248. return True
  249. try:
  250. res = await self._api_post("/api/v1/webhook",
  251. {"url": webhook_url, "events": ["new-message", "updated-message"]})
  252. status = res.get("status", 0)
  253. if 200 <= status < 300:
  254. logger.info("[bluebubbles] webhook registered with server: %s", log_url)
  255. return True
  256. logger.warning("[bluebubbles] webhook registration returned status %s: %s", status, res.get("message"))
  257. return False
  258. except Exception as exc:
  259. logger.warning("[bluebubbles] failed to register webhook with server: %s", exc)
  260. return False
  261. async def _unregister_webhook(self) -> bool:
  262. """Remove *all* registrations matching our URL (cleans up crash duplicates)."""
  263. if not self.client:
  264. return False
  265. removed = False
  266. try:
  267. for wh in await self._find_registered_webhooks(self._webhook_register_url):
  268. if wh_id := wh.get("id"):
  269. (await self.client.delete(self._api_url(f"/api/v1/webhook/{wh_id}"))).raise_for_status()
  270. removed = True
  271. if removed:
  272. logger.info("[bluebubbles] webhook unregistered: %s", self._webhook_register_url_for_log)
  273. except Exception as exc:
  274. logger.debug("[bluebubbles] failed to unregister webhook (non-critical): %s", exc)
  275. return removed
  276. # --- Chat GUID resolution ---
  277. async def _resolve_chat_guid(self, target: str) -> Optional[str]:
  278. """Resolve an email/phone to a chat GUID (raw ``a;-;b`` GUIDs pass through). Matches strictly on
  279. ``chatIdentifier`` / ``identifier``; participant membership is intentionally NOT a fallback —
  280. the same contact appears in a 1:1 DM and any number of groups, so a participant match could
  281. leak a DM reply into a group thread. ``None`` lets the caller create a fresh DM.
  282. See #24157.
  283. """
  284. target = (target or "").strip()
  285. if not target or ";" in target:
  286. return target or None
  287. if target in self._guid_cache:
  288. self._guid_cache.move_to_end(target)
  289. return self._guid_cache[target]
  290. with suppress(Exception):
  291. payload = await self._api_post("/api/v1/chat/query", {"limit": 100, "offset": 0})
  292. for chat in payload.get("data", []) or []:
  293. if (chat.get("chatIdentifier") or chat.get("identifier")) != target:
  294. continue
  295. if guid := chat.get("guid") or chat.get("chatGuid"):
  296. self._guid_cache[target] = guid
  297. while len(self._guid_cache) > _GUID_CACHE_SIZE:
  298. self._guid_cache.popitem(last=False)
  299. return guid
  300. return None
  301. async def _create_chat_for_handle(self, address: str, message: str) -> SendResult:
  302. """Create a new chat by sending the first message to *address*."""
  303. return await self._post_message(
  304. "/api/v1/chat/new", {"addresses": [address], "message": message, "tempGuid": _temp_guid()})
  305. # --- Text sending ---
  306. @staticmethod
  307. def truncate_message(content: str, max_length: int = MAX_TEXT_LENGTH) -> list[str]:
  308. # Base splitter minus "(1/3)" pagination suffixes — iMessage bubbles flow naturally.
  309. return [_PAGINATION_SUFFIX_RE.sub("", c) for c in BasePlatformAdapter.truncate_message(content, max_length)]
  310. async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None,
  311. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  312. text = self.format_message(content)
  313. if not text:
  314. return SendResult(success=False, error="BlueBubbles send requires text")
  315. # Each paragraph becomes its own iMessage bubble; truncate any still too long.
  316. paragraphs = [p.strip() for p in re.split(r'\n\s*\n', text) if p.strip()] or [text]
  317. chunks = [c for para in paragraphs for c in (
  318. [para] if len(para) <= self.MAX_MESSAGE_LENGTH else self.truncate_message(para, self.MAX_MESSAGE_LENGTH))]
  319. last = SendResult(success=True)
  320. for chunk in chunks:
  321. guid = await self._resolve_chat_guid(chat_id)
  322. if not guid:
  323. if self._private_api_enabled and ("@" in chat_id or _ADDRESS_RE.match(chat_id)): # address → new chat
  324. return await self._create_chat_for_handle(chat_id, chunk)
  325. return SendResult(success=False, error=f"BlueBubbles chat not found for target: {chat_id}")
  326. payload: dict[str, Any] = {"chatGuid": guid, "tempGuid": _temp_guid(), "message": chunk}
  327. if reply_to and self._private_api_enabled and self._helper_connected:
  328. payload.update(method="private-api", selectedMessageGuid=reply_to, partIndex=0)
  329. if not (last := await self._post_message("/api/v1/message/text", payload)).success:
  330. return last
  331. return last
  332. # --- Media sending (outbound) ---
  333. async def _send_attachment(self, chat_id: str, file_path: str, filename: Optional[str] = None,
  334. caption: Optional[str] = None, is_audio_message: bool = False) -> SendResult:
  335. """Send a file attachment via BlueBubbles multipart upload."""
  336. if not self.client:
  337. return SendResult(success=False, error="Not connected")
  338. if not await asyncio.to_thread(os.path.isfile, file_path):
  339. return SendResult(success=False, error=f"File not found: {file_path}")
  340. guid = await self._resolve_chat_guid(chat_id)
  341. if not guid:
  342. return SendResult(success=False, error=f"Chat not found: {chat_id}")
  343. fname = filename or os.path.basename(file_path)
  344. try:
  345. # httpx's async multipart iterator reads file objects through a sync chunk generator —
  346. # read the bytes off the event-loop thread first.
  347. payload = await asyncio.to_thread(Path(file_path).read_bytes)
  348. data: dict[str, str] = {"chatGuid": guid, "name": fname, "tempGuid": uuid.uuid4().hex}
  349. if is_audio_message:
  350. data["isAudioMessage"] = "true"
  351. res = await self.client.post(self._api_url("/api/v1/message/attachment"), data=data, timeout=120,
  352. files={"attachment": (fname, payload, "application/octet-stream")})
  353. res.raise_for_status()
  354. result = res.json()
  355. if caption:
  356. await self.send(chat_id, caption)
  357. if result.get("status") == 200:
  358. rdata = result.get("data") or {}
  359. return SendResult(success=True, message_id=rdata.get("guid") if isinstance(rdata, dict) else None,
  360. raw_response=result)
  361. return SendResult(success=False, error=result.get("message", "Attachment upload failed"))
  362. except Exception as e:
  363. return SendResult(success=False, error=str(e))
  364. async def send_image(self, chat_id: str, image_url: str, caption: Optional[str] = None,
  365. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> SendResult:
  366. try:
  367. from gateway.platforms.base import cache_image_from_url
  368. return await self._send_attachment(chat_id, await cache_image_from_url(image_url), caption=caption)
  369. except Exception:
  370. return await super().send_image(chat_id, image_url, caption, reply_to)
  371. async def send_image_file(self, chat_id, image_path, caption=None, reply_to=None, **kw) -> SendResult:
  372. return await self._send_attachment(chat_id, image_path, caption=caption)
  373. async def send_voice(self, chat_id, audio_path, caption=None, reply_to=None, is_voice=None, **kw) -> SendResult:
  374. # is_voice=False is a plain audio MEDIA file (music, a sound effect): a normal attachment,
  375. # never an iMessage voice memo.
  376. return await self._send_attachment(chat_id, audio_path, caption=caption, is_audio_message=is_voice is not False)
  377. async def send_video(self, chat_id, video_path, caption=None, reply_to=None, **kw) -> SendResult:
  378. return await self._send_attachment(chat_id, video_path, caption=caption)
  379. async def send_document(self, chat_id, file_path, caption=None, file_name=None, reply_to=None, **kw) -> SendResult:
  380. return await self._send_attachment(chat_id, file_path, filename=file_name, caption=caption)
  381. async def send_animation(self, chat_id, animation_url, caption=None, reply_to=None, metadata=None) -> SendResult:
  382. return await self.send_image(chat_id, animation_url, caption, reply_to, metadata)
  383. # --- Typing indicators / read receipts (private API only) ---
  384. async def send_typing(self, chat_id: str, metadata=None) -> None:
  385. await self._private_api_chat_call(chat_id, "typing", "post")
  386. async def stop_typing(self, chat_id: str) -> None:
  387. await self._private_api_chat_call(chat_id, "typing", "delete")
  388. async def mark_read(self, chat_id: str) -> bool:
  389. return await self._private_api_chat_call(chat_id, "read", "post")
  390. # --- Chat info ---
  391. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  392. is_group = ";+;" in (chat_id or "")
  393. info: dict[str, Any] = {"name": chat_id, "type": "group" if is_group else "dm"}
  394. with suppress(Exception):
  395. if guid := await self._resolve_chat_guid(chat_id):
  396. res = await self._api_get(f"/api/v1/chat/{quote(guid, safe='')}?with=participants")
  397. data = (res or {}).get("data", {})
  398. info["name"] = data.get("displayName") or data.get("chatIdentifier") or chat_id
  399. participants = [addr for p in data.get("participants", []) or []
  400. if (addr := (p.get("address") or "").strip())]
  401. if participants:
  402. info["participants"] = participants
  403. return info
  404. def format_message(self, content: str) -> str:
  405. return strip_markdown(content, keep_link_targets=True) # iMessage auto-links bare URLs only
  406. # --- Inbound attachment downloading ---
  407. async def _download_attachment(self, att_guid: str, att_meta: dict[str, Any]) -> Optional[str]:
  408. """Download an attachment and cache it locally; local path or None on failure."""
  409. if not self.client:
  410. return None
  411. try:
  412. resp = await self.client.get(self._api_url(f"/api/v1/attachment/{quote(att_guid, safe='')}/download"),
  413. timeout=60, follow_redirects=True)
  414. resp.raise_for_status()
  415. data = resp.content
  416. mime = (att_meta.get("mimeType") or "").lower()
  417. if mime.startswith("image/"):
  418. return await cache_image_from_bytes_async(data, _closed_ext(mime, _BLUEBUBBLES_IMAGE_EXT_OVERRIDES, ".jpg"))
  419. if mime.startswith("audio/"):
  420. return await cache_audio_from_bytes_async(data, _closed_ext(mime, _BLUEBUBBLES_AUDIO_EXT_OVERRIDES, ".mp3"))
  421. # Videos, documents, and everything else
  422. return await cache_document_from_bytes_async(data, att_meta.get("transferName", "") or f"file_{uuid.uuid4().hex[:8]}")
  423. except Exception as exc:
  424. logger.warning("[bluebubbles] failed to download attachment %s: %s", _redact(att_guid), exc)
  425. return None
  426. # --- Webhook handling ---
  427. def _extract_payload_record(self, payload: dict[str, Any]) -> Optional[dict[str, Any]]:
  428. data = payload.get("data")
  429. if isinstance(data, dict):
  430. return data
  431. if isinstance(data, list) and (first := next((i for i in data if isinstance(i, dict)), None)):
  432. return first
  433. if isinstance(payload.get("message"), dict):
  434. return payload.get("message")
  435. return payload if isinstance(payload, dict) else None
  436. @staticmethod
  437. def _value(*candidates: Any) -> Optional[str]:
  438. return next((c.strip() for c in candidates if isinstance(c, str) and c.strip()), None)
  439. @staticmethod
  440. def _parse_webhook_body(raw: bytes) -> Any:
  441. """Decode a webhook body: JSON, else form-encoded with a JSON field."""
  442. body = raw.decode("utf-8", errors="replace")
  443. try:
  444. return json.loads(body)
  445. except Exception:
  446. form = parse_qs(body)
  447. payload_str = (form.get("payload") or form.get("data") or form.get("message") or [""])[0]
  448. return json.loads(payload_str) if payload_str else {}
  449. async def _collect_attachments(self, record: dict[str, Any]):
  450. """Download inbound attachments; returns (media_urls, media_types, msg_type)."""
  451. media_urls: list[str] = []
  452. media_types: list[str] = []
  453. msg_type = MessageType.TEXT
  454. for att in record.get("attachments") or []:
  455. att_guid = att.get("guid", "")
  456. cached = await self._download_attachment(att_guid, att) if att_guid else None
  457. if not cached:
  458. continue
  459. mime = (att.get("mimeType") or "").lower()
  460. media_urls.append(cached)
  461. media_types.append(mime)
  462. is_voice = mime.startswith("audio/") or (att.get("uti") or "").endswith("caf")
  463. msg_type = (MessageType.PHOTO if mime.startswith("image/") else MessageType.VOICE if is_voice
  464. else MessageType.VIDEO if mime.startswith("video/") else MessageType.DOCUMENT)
  465. if len(media_urls) > 1 and any(m.split("/")[0] == "image" for m in media_types): # any image → PHOTO
  466. msg_type = MessageType.PHOTO
  467. return media_urls, media_types, msg_type
  468. def _webhook_token(self, request) -> Optional[str]:
  469. return (request.query.get("password") or request.query.get("guid") or request.headers.get("x-password")
  470. or request.headers.get("x-guid") or request.headers.get("x-bluebubbles-guid"))
  471. def _resolve_chat_and_sender(self, payload: dict[str, Any], record: dict[str, Any]):
  472. """Returns ``(chat_guid, chat_identifier, sender)`` from the many BlueBubbles payload shapes."""
  473. chat_guid = self._value(record.get("chatGuid"), payload.get("chatGuid"), record.get("chat_guid"),
  474. payload.get("chat_guid"), payload.get("guid"))
  475. # BlueBubbles v1.9+ payloads omit top-level chatGuid; it's nested under data.chats[0].guid.
  476. _chats = record.get("chats") or []
  477. if not chat_guid and _chats and isinstance(_chats[0], dict):
  478. chat_guid = _chats[0].get("guid") or _chats[0].get("chatGuid")
  479. chat_identifier = self._value(record.get("chatIdentifier"), record.get("identifier"),
  480. payload.get("chatIdentifier"), payload.get("identifier"))
  481. handle = record.get("handle")
  482. sender = (self._value(handle.get("address") if isinstance(handle, dict) else None, record.get("sender"),
  483. record.get("from"), record.get("address")) or chat_identifier or chat_guid)
  484. if not (chat_guid or chat_identifier) and sender:
  485. chat_identifier = sender
  486. return chat_guid, chat_identifier, sender
  487. async def _handle_webhook(self, request):
  488. from aiohttp import web
  489. if self._webhook_token(request) != self.password:
  490. return web.json_response({"error": "unauthorized"}, status=401)
  491. try:
  492. payload = self._parse_webhook_body(await request.read())
  493. except Exception as exc:
  494. logger.error("[bluebubbles] webhook parse error: %s", exc)
  495. return web.json_response({"error": "invalid payload"}, status=400)
  496. event_type = self._value(payload.get("type"), payload.get("event")) or ""
  497. if event_type and event_type not in _MESSAGE_EVENTS: # ack non-message events silently
  498. return _ok()
  499. record = self._extract_payload_record(payload) or {}
  500. if record.get("isFromMe") or record.get("fromMe") or record.get("is_from_me"):
  501. return _ok()
  502. assoc_type = record.get("associatedMessageType")
  503. if isinstance(assoc_type, int) and assoc_type in _TAPBACK_CODES: # tapback reactions delivered as messages
  504. return _ok()
  505. text = self._value(record.get("text"), record.get("message"), record.get("body")) or ""
  506. chat_guid, chat_identifier, sender = self._resolve_chat_and_sender(payload, record)
  507. session_chat_id = chat_guid or chat_identifier
  508. is_group = bool(record.get("isGroup")) or (";+;" in (chat_guid or ""))
  509. # Mention gate BEFORE the attachment downloads: an unmentioned group message must not
  510. # pull every attachment through the REST API only to be dropped.
  511. if is_group and self.require_mention:
  512. if not self._message_matches_mention_patterns(text):
  513. logger.debug("[bluebubbles] ignoring group message (require_mention=true, no mention pattern matched)")
  514. return _ok()
  515. text = self._clean_mention_text(text)
  516. media_urls, media_types, msg_type = await self._collect_attachments(record)
  517. if not text and media_urls:
  518. text = "(attachment)"
  519. if not sender or not (chat_guid or chat_identifier) or not text:
  520. return web.json_response({"error": "missing message fields"}, status=400)
  521. source = self.build_source(chat_id=session_chat_id, chat_name=chat_identifier or sender,
  522. chat_type="group" if is_group else "dm", user_id=sender, user_name=sender,
  523. chat_id_alt=chat_identifier)
  524. event = MessageEvent(
  525. text=text, message_type=msg_type, source=source, raw_message=payload,
  526. message_id=self._value(record.get("guid"), record.get("messageGuid"), record.get("id")),
  527. reply_to_message_id=self._value(record.get("threadOriginatorGuid"), record.get("associatedMessageGuid")),
  528. media_urls=media_urls, media_types=media_types)
  529. task = asyncio.create_task(self.handle_message(event))
  530. self._background_tasks.add(task)
  531. task.add_done_callback(self._background_tasks.discard)
  532. if self.send_read_receipts and session_chat_id: # fire-and-forget read receipt
  533. asyncio.create_task(self.mark_read(session_chat_id))
  534. return _ok()
  535. # --- Plugin hooks (registered via register(ctx) below) ---
  536. _INSTALL_HINT = "BlueBubbles: aiohttp/httpx missing or BLUEBUBBLES_SERVER_URL/BLUEBUBBLES_PASSWORD not configured"
  537. def _is_connected(config) -> bool:
  538. """Server URL + password present in ``PlatformConfig.extra`` (the env table seeds it) or the env."""
  539. extra = getattr(config, "extra", None) or {}
  540. if extra.get("server_url") and extra.get("password"):
  541. return True
  542. import hermes_cli.gateway as gateway_mod
  543. return all((gateway_mod.get_env_value(n) or "").strip() for n in ("BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_PASSWORD"))
  544. async def _standalone_send(pconfig, chat_id: str, message: str, *, thread_id: Optional[str] = None,
  545. media_files: Optional[list] = None, force_document: bool = False, **_kw) -> dict[str, Any]:
  546. """Out-of-process send (cron without a co-resident gateway): one-shot adapter connect → send →
  547. disconnect against the BlueBubbles REST API. Text only; ``thread_id``/``media_files``/
  548. ``force_document`` are signature parity (send_message drops media with a warning)."""
  549. from gateway.platforms._shared import send_error
  550. if not check_bluebubbles_requirements():
  551. return send_error("BlueBubbles requirements not met (need aiohttp + httpx).")
  552. try:
  553. adapter = BlueBubblesAdapter(PlatformConfig(extra=dict(getattr(pconfig, "extra", None) or {})))
  554. if not await adapter.connect():
  555. return send_error("BlueBubbles: failed to connect to server")
  556. try:
  557. result = await adapter.send(chat_id, message)
  558. finally:
  559. await adapter.disconnect()
  560. if not result.success:
  561. return send_error(f"BlueBubbles send failed: {result.error}")
  562. return {"success": True, "platform": "bluebubbles", "chat_id": chat_id, "message_id": result.message_id}
  563. except Exception as e:
  564. logger.debug("BlueBubbles standalone send failed", exc_info=True)
  565. return send_error(f"BlueBubbles send failed: {e}")
  566. def interactive_setup() -> None:
  567. """Configure BlueBubbles iMessage gateway (``hermes setup`` / ``hermes gateway setup``)."""
  568. from hermes_cli.setup import _info, print_header, print_success, prompt, prompt_yes_no
  569. from hermes_cli.setup_platforms import _prompt_allowlist, _save_port, declines_reconfigure, save_prompted
  570. print_header("BlueBubbles (iMessage)")
  571. if declines_reconfigure("BlueBubbles", "Reconfigure BlueBubbles?", "BLUEBUBBLES_SERVER_URL"):
  572. return
  573. _info("Connects Hermes to iMessage via BlueBubbles — a free, open-source",
  574. "macOS server that bridges iMessage to any device.",
  575. " Requires a Mac running BlueBubbles Server v1.0.0+",
  576. " Download: https://bluebubbles.app/", None,
  577. "In BlueBubbles Server → Settings → API, note your Server URL and Password.", None)
  578. for label, env_var, secret, what, transform in (
  579. ("BlueBubbles server URL (e.g. http://192.168.1.10:1234)", "BLUEBUBBLES_SERVER_URL", False, "Server URL",
  580. lambda v: v.rstrip("/")),
  581. ("BlueBubbles server password", "BLUEBUBBLES_PASSWORD", True, "Password", None),
  582. ):
  583. if not save_prompted(env_var, label, password=secret, transform=transform,
  584. skip_msg=f"{what} is required — skipping BlueBubbles setup"):
  585. return
  586. print_success("BlueBubbles credentials saved")
  587. _info(None, "🔒 Security: Restrict who can message your bot",
  588. " Use iMessage addresses: email (user@icloud.com) or phone (+15551234567)", None)
  589. _prompt_allowlist("BLUEBUBBLES_ALLOWED_USERS", "Allowed iMessage addresses (comma-separated, leave empty for open access)",
  590. "BlueBubbles allowlist configured", "⚠️ No allowlist set — anyone who can iMessage you can use the bot!")
  591. _info(None, "📬 Home Channel: phone or email for cron job delivery and notifications.",
  592. " You can also set this later with /set-home in your iMessage chat.")
  593. save_prompted("BLUEBUBBLES_HOME_CHANNEL", "Home channel address (leave empty to set later)")
  594. _info(None, "Advanced settings (defaults are fine for most setups):")
  595. if prompt_yes_no("Configure webhook listener settings?", False):
  596. _save_port("BLUEBUBBLES_WEBHOOK_PORT", prompt("Webhook listener port (default: 8645)"), "8645")
  597. _info(None, "Requires the BlueBubbles Private API helper for typing indicators,",
  598. "read receipts, and tapback reactions. Basic messaging works without it.",
  599. " Install: https://docs.bluebubbles.app/helper-bundle/installation")
  600. # System-prompt platform hint (PlatformEntry.platform_hint); cached-prompt bytes, keep stable.
  601. _PLATFORM_HINT = (
  602. # The adapter runs strip_markdown(keep_link_targets=True): markers vanish, the layout stays.
  603. "You are texting via iMessage (BlueBubbles). Replies arrive as plain text bubbles, so write like a person "
  604. "texting: short and conversational, answer first, no preamble or recap. Markdown does not render and is "
  605. "stripped, so skip headers, tables, code fences and backticks; for a few items use short lines or a "
  606. "sentence rather than nested bullets. Put a command or code snippet on its own line as plain text so it "
  607. "can be copied. Write links as bare URLs (iMessage auto-links them). "
  608. "You can send files natively: write MEDIA:/absolute/path/to/file in your response. "
  609. "Images (.jpg, .png, .heic) appear as photos and other files arrive as attachments."
  610. )
  611. def register(ctx) -> None:
  612. """Plugin entry point — called by the Hermes plugin system."""
  613. from . import gateway_env # env -> GatewayConfig bridge (gateway.config_env)
  614. ctx.register_platform(
  615. name="bluebubbles", label="BlueBubbles (iMessage)", adapter_factory=BlueBubblesAdapter,
  616. dashboard_description="Use Hermes through iMessage via a BlueBubbles server.",
  617. docs_url="https://bluebubbles.app/",
  618. dashboard_env_vars=("BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_PASSWORD", "BLUEBUBBLES_ALLOWED_USERS"),
  619. check_fn=check_bluebubbles_requirements, is_connected=_is_connected,
  620. config_connected_fn=config_connected_extra("server_url", "password"),
  621. required_env=["BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_PASSWORD"], install_hint=_INSTALL_HINT,
  622. setup_fn=interactive_setup,
  623. cron_deliver_env_var="BLUEBUBBLES_HOME_CHANNEL",
  624. standalone_sender_fn=_standalone_send, # out-of-process cron / send_message
  625. # 0 = send_message does not pre-chunk: the adapter's send() splits per paragraph and
  626. # truncates itself (MAX_MESSAGE_LENGTH), exactly as the former core sender did.
  627. max_message_length=0, pii_safe=True, emoji="💬", allow_update_command=True,
  628. platform_hint=_PLATFORM_HINT,
  629. display_tier="low",
  630. env_overrides=gateway_env.ENV_OVERRIDES,
  631. env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS, **gateway_env.AUTHZ,
  632. )