napcat-cli 2.0.0__py3-none-any.whl

napcat_cli/data/skills-fs.d/skill-agents.md

@@ -0,0 +1,42 @@
+# NapCat CLI Skill — Agent Guide
+
+This skill exposes a NapCat QQ bot through `skills-fs`, a virtual filesystem engine.
+Before the filesystem is available, an external daemon must be started.
+
+## Daemon requirements
+
+- `skills-fs` Go binary (can be shipped with this skill)
+- `watch.py` NapCat WebSocket listener / HTTP provider (Python daemon)
+- NapCat server reachable via HTTP and WebSocket
+
+## How to start
+
+```bash
+# 1. Start NapCat (e.g. via Docker)
+docker compose -f NapcatDocker/docker-compose.yml up -d
+
+# 2. Start the NapCat HTTP/WebSocket provider daemon
+python3 napcat-cli/daemon/watch.py ~/.napcat-data/daemon.json
+
+# 3. Start skills-fs FUSE
+skills-fs fuse   --config ~/.napcat-cli/skills-fs.json   --mountpoint ~/.napcat-cli/skills/napcat-cli   --allow-other   --log-file ~/.napcat-cli/skills-fuse.log
+```
+
+## Filesystem layout
+
+- `/SKILL.md` — skill documentation
+- `/AGENTS.md` — this guide
+- `/persona.md` — bot persona / system prompt
+- `/napcat/` — API endpoints and data directories
+  - `/napcat/send_group`, `/napcat/send_private` — write JSON to send messages
+  - `/napcat/events/`, `/napcat/alerts/` — real-time events and notifications
+  - `/napcat/groups/{group_id}/{recent,1days,7days,30days,90days}/{message_id}` — browse group messages; write to `/napcat/groups/{group_id}/send` to reply
+  - `/napcat/friends/{user_id}/{recent,1days,7days,30days,90days}/{message_id}` — browse private messages; write to `/napcat/friends/{user_id}/send` to reply
+
+Each directory contains an `AGENTS.md` explaining its purpose and parameters.
+
+## Shipped-with-skills-fs option
+
+This skill can be bundled with a pre-built `skills-fs` binary. Set the binary path in
+`~/.napcat-data/daemon.json` under `skillsFs.binary` and start the daemon with
+`napcat daemon start`.

napcat_cli/data/skills-fs.d/skill-body.md

@@ -0,0 +1,102 @@
+# NapCat CLI Skill (skills-fs mounted)
+
+> ⚙️ **Mount state: skills-fs IS mounted.** This is the *generated* post-mount SKILL.md
+> (skills-fs overwrote the static one when it mounted the `/napcat/` tree). You now have
+> **two equivalent interfaces**: the `napcat` CLI below, and the `/napcat/` virtual
+> filesystem. Either works; pick whichever fits. If the mount ever disappears, the CLI
+> keeps working — see `references/mounting.md` for the FUSE D-state hazard & recovery.
+
+Access QQ bot capabilities through the `napcat` CLI **or** the `/napcat/` FUSE tree.
+
+## When to Use
+- Send private or group messages, read events/alerts, manage groups/friends/message lifecycle.
+- Query group/friend metadata; poke members; call raw API endpoints.
+
+## Prerequisites
+- NapCat daemon running, HTTP `/invoke` at `http://127.0.0.1:18821`, connected to NapCat WS (`:18800`).
+- Bot online (`napcat status`).
+- `skills-fs` FUSE mounted at the skill dir (this state) for the filesystem interface.
+
+---
+
+# Interface A — the `napcat` CLI (no mount required)
+
+All operations are CLI commands. Most useful when you don't want to touch the FUSE tree.
+
+```bash
+napcat status                      # bot online?
+napcat events                      # recent events (JSON)
+napcat alerts                      # pending alerts
+napcat send private <uid> -m "hi"
+napcat send group <gid> -m "hi" --at <uid>
+napcat reply <msg_id> -m "回复"
+napcat group list | members <gid> | info <gid>
+napcat friend list
+napcat daemon status               # daemon + recent log
+```
+
+### Read-only
+`napcat status` · `napcat events [--since T] [--type X]` · `napcat alerts [--clear]` · `napcat msg <id>` · `napcat group list/members/info/essence <gid>` · `napcat friend list` · `napcat file list-group <gid>`
+
+### Sending
+`napcat send group|private <id> -m "..." [--at <uid>] [--image <path>] [--file <path>]` · `napcat reply <id> -m "..."` · `napcat recall <id> [--group <gid>]`
+
+### Group ops
+`napcat group {poke|mute|unmute|kick|admin|rename|remark|announce|set_essence} <gid> ...`
+
+### Friend ops / lifecycle / raw
+`napcat friend {list|remark|info|delete} ...` · `napcat send_poke` · `napcat send_forward` · `napcat api <endpoint> [-d JSON]`
+
+### Wake / debug
+`napcat wake test` · `napcat wake --dry-run` · `napcat wake --reason AT_ME --prompt "..."`
+
+### Persona
+On QQ, reply in persona — load `~/.napcat-data/skills/persona.md` first. Do **not** say "我是AI".
+
+---
+
+# Interface B — the `/napcat/` FUSE tree (this mount)
+
+Read an API file to fetch data; write JSON to a write-enabled file to act. Written JSON is
+forwarded as provider params.
+
+```bash
+cat napcat/events                       # read recent events
+echo '{"group_id":123456,"message":"hi"}' > napcat/send_group   # send group msg
+echo '{"alert_name":"NEW_MESSAGE"}' > napcat/clear_alert         # clear an alert
+```
+
+### Send / message mgmt
+`send_group`=send_group_msg · `send_private`=send_private_msg · `delete`=delete_msg · `get_events` · `get_alerts` · `clear_alert` · `clear_all_alerts`
+
+### Group management (write JSON params)
+`group_kick` · `group_ban` · `group_admin` · `group_name` · `group_leave` · `group_essence` · `group_members`(read) · `group_info`(read) · `group_honor`(read) · `group_forward`
+
+### Friend / system
+`friend_list` · `friend_add` · `friend_info` · `status` · `cookie` · `bkn` · `get_image` · `ocr` · `approve_request` · `reject_request`
+
+### Per-conversation directories
+`napcat/groups/{group_id}/{recent|1days|7days|30days|90days}/{message_id}/` — browse messages;
+write to `napcat/groups/{group_id}/send` to reply. Same shape under `napcat/friends/{user_id}/`.
+
+## Procedure (FUSE)
+1. Pick the action file (e.g. `napcat/send_group`).
+2. Read for data; write JSON params for actions. Read back to verify.
+3. For group/friend message browse, use the per-conversation directories above.
+
+## Pitfalls
+- **CLI vs FUSE poke**: `napcat group poke` works; the HTTP `send_group_poke` often doesn't. Prefer the CLI for poke.
+- **Offline**: check `napcat status` / read `napcat/status` before API calls. If offline, `napcat daemon start`.
+- **Rate limits**: `send_like` → error 1400 = rate-limited; wait ≥30s. >~10 msg/min to one target may throttle.
+- **Recall**: own messages ≤2 min; others' ≤20 s (admin/owner exempt).
+- **events file**: only recent ~50 in memory; `alerts` keeps fuller history. Newest-first; use `?limit=N` (e.g. `cat napcat/events?limit=20`) — note the daemon defaults to a small result set.
+- **Files/images**: local paths need `file:///` prefix; `http(s)://` and `base64://` also OK.
+- **Write payload**: write JSON params only (`{"group_id":"123","message":"hi"}`), NOT the full OneBot envelope — the provider wraps it. Non-JSON writes fail.
+- **Unsupported APIs**: `retcode:200` + "不支持的Api" → feature unavailable on this NapCat build (e.g. `send_group_notice`, `get_essence_list`).
+- **Kernel errors**: `NodeIKernel...` = kernel timeout (bot may be offline); `ERR_NEED_MAKEUP` = QQ risk control; `ERR_NOT_GROUP_ADMIN` / `ERR_NOT_IN_GROUP` / `ERR_SEND_MSG_FREQ_LIMIT` are self-explanatory.
+- **Mount lost (ENOTCONN)**: fall back to the CLI; remount via `napcat daemon restart` (skills-fs remounts).
+
+## Verification
+- `napcat status` / `cat napcat/status` → online.
+- `cat napcat/events` → events returned.
+- Write `napcat/send_group` → message appears in the target group.

napcat_cli/lib/__init__.py

@@ -0,0 +1 @@
+"""napcat-cli library."""

napcat_cli/lib/api.py

@@ -0,0 +1,258 @@
+"""NapCat HTTP API client."""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.request
+import urllib.error
+from pathlib import Path
+from typing import Any
+
+from .config import get_config, DATA_DIR
+
+
+class NapCatAPI:
+    """HTTP client for NapCat OneBot 11 API."""
+
+    def __init__(self, api_url: str | None = None, token: str | None = None, timeout: int | None = None):
+        cfg = get_config()
+        self.api_url = (api_url or os.environ.get("NAPCAT_API_URL") or cfg.api_url).rstrip("/")
+        self.token = token or os.environ.get("NAPCAT_TOKEN") or cfg.token
+        self.timeout = timeout if timeout is not None else 30
+        self.echo_counter = 0
+
+        # Load or create API availability cache
+        self._load_api_cache()
+
+    def _load_api_cache(self) -> None:
+        """Load API availability cache from disk. No probe — cache is built lazily."""
+        self._unsupported_apis: set[str] = set()
+        cache_file = DATA_DIR / "napcat_api_cache.json"
+        try:
+            if cache_file.exists():
+                data = json.loads(cache_file.read_text())
+                ts = data.get("timestamp", 0)
+                import time
+                if time.time() - ts < 3600:  # 1 hour TTL
+                    self._unsupported_apis = set(data.get("unsupported", []))
+        except Exception:
+            pass
+
+    def _save_api_cache(self) -> None:
+        """Persist API availability cache to disk."""
+        try:
+            import time
+            cache_file = DATA_DIR / "napcat_api_cache.json"
+            cache_file.parent.mkdir(parents=True, exist_ok=True)
+            cache_file.write_text(json.dumps({
+                "timestamp": int(time.time()),
+                "unsupported": list(self._unsupported_apis),
+            }))
+        except Exception:
+            pass
+
+    def _next_echo(self) -> str:
+        """Generate unique echo ID for request tracking."""
+        import secrets
+        return secrets.token_hex(6)
+
+    def request(self, endpoint: str, method: str = "POST", json_body: dict | None = None, timeout: int | None = None) -> dict:
+        """Make a raw API request.
+
+        Args:
+            endpoint: API endpoint name (e.g., "get_login_info", ".send_poke")
+            method: HTTP method
+            json_body: JSON body for POST/PUT requests
+            timeout: Per-call timeout in seconds. Falls back to self.timeout (default 30).
+
+        Returns:
+            Parsed JSON response as dict.
+        """
+        url = f"{self.api_url}/{endpoint}"
+        call_timeout = timeout if timeout is not None else self.timeout
+
+        body = b""
+        if method.upper() in ("POST", "PUT", "PATCH") and json_body is not None:
+            body = json.dumps(json_body).encode("utf-8")
+
+        req = urllib.request.Request(url, data=body, method=method)
+        req.add_header("Content-Type", "application/json")
+        if self.token:
+            req.add_header("Authorization", f"Bearer {self.token}")
+
+        try:
+            with urllib.request.urlopen(req, timeout=call_timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                return json.loads(raw)
+        except urllib.error.HTTPError as e:
+            raw = e.read().decode("utf-8", errors="replace")
+            try:
+                err = json.loads(raw)
+            except json.JSONDecodeError:
+                err = {"status": "error", "message": raw, "retcode": e.code}
+            print(f"API error {e.code}: {err}", file=sys.stderr)
+            return err
+        except urllib.error.URLError as e:
+            err = {
+                "status": "error",
+                "message": f"Connection failed: {e.reason}",
+                "retcode": -1,
+                "hint": self._connection_hint(),
+            }
+            print(f"Connection error: {err['message']}", file=sys.stderr)
+            return err
+        except Exception as e:
+            err = {
+                "status": "error",
+                "message": str(e),
+                "retcode": -1,
+                "hint": self._connection_hint(),
+            }
+            print(f"Error: {err['message']}", file=sys.stderr)
+            return err
+    def _normalize(self, params: dict) -> dict:
+        """Normalize params for NapCat 4.x - convert string IDs to int."""
+        numeric_fields = {
+            "group_id", "user_id", "message_id", "flag",
+            "duration", "count", "status", "ext_status", "battery_status",
+            "font", "busid", "page", "page_size", "role",
+        }
+        bool_fields = {
+            "no_cache", "enable", "approve", "reject_add_request",
+            "auto_escape", "enable_force_push", "upload_file",
+        }
+        result: dict = {}
+        for k, v in params.items():
+            if k in numeric_fields and isinstance(v, str):
+                try:
+                    result[k] = int(v)
+                except ValueError:
+                    result[k] = v
+            elif k in bool_fields and isinstance(v, str):
+                result[k] = v.lower() in ("true", "1", "yes")
+            else:
+                result[k] = v
+        return result
+
+    def is_online(self, _cache_ttl: int = 30) -> bool:
+        """Check if NapCat bot is currently online.
+
+        Caches result for _cache_ttl seconds to avoid excessive polling.
+        """
+        import time
+        now = time.time()
+        if hasattr(self, "_online_cache") and (now - self._online_cache["ts"]) < _cache_ttl:
+            return self._online_cache["online"]
+
+        result = self.request("get_status", method="POST", json_body={}, timeout=5)
+        data = result.get("data", {})
+        online = bool(data.get("online", False))
+        self._online_cache = {"ts": now, "online": online}
+        return online
+
+    @staticmethod
+    def friendly_error(raw_message: str) -> str:
+        """Map NapCat kernel error messages to user-friendly descriptions."""
+        mapping: dict[str, str] = {
+            "NTEvent serviceAndMethod:NodeIKernelMsgService/sendMsgInfoListener/onMsgInfoListener": "NapCat 内核超时，bot 可能离线",
+            "ERR_NEED_MAKEUP": "QQ 风控限制，操作被拒绝",
+            "ERR_NOT_GROUP_ADMIN": "不是群管理员",
+            "ERR_NOT_IN_GROUP": "不在该群中",
+            "ERR_REQUEST_COOLDOWN": "请求冷却中，请稍后再试",
+            "ERR_SEND_MSG_FREQ_LIMIT": "发送频率限制，请稍后再试",
+            "ERR_GROUP_NOT_FOUND": "群不存在或已退群",
+        }
+        for pattern, friendly in mapping.items():
+            if pattern in raw_message:
+                return friendly
+        # If message contains kernel internal path, simplify it
+        if "NodeIKernel" in raw_message:
+            return "NapCat 内核响应超时"
+        return raw_message
+
+    # Cache of known unsupported APIs (populated on first use)
+    _unsupported_apis: set[str] | None = None
+
+    def is_api_supported(self, action: str) -> bool | None:
+        """Check if a NapCat API action is supported.
+
+        Returns True if known supported, False if known unsupported,
+        None if unknown (hasn't been tested yet).
+        """
+        if self._unsupported_apis is None:
+            self._unsupported_apis = set()
+        if action in self._unsupported_apis:
+            return False
+        return None  # unknown
+
+    def mark_api_unsupported(self, action: str) -> None:
+        """Record that an API action is not supported by this NapCat instance."""
+        if self._unsupported_apis is None:
+            self._unsupported_apis = set()
+        self._unsupported_apis.add(action)
+        self._save_api_cache()
+
+
+    def call(self, action: str, timeout: int | None = None, **params: Any) -> dict:
+        """Call an API action with parameters.
+
+        Args:
+            action: Action name (e.g., "send_msg", "get_group_info")
+            timeout: Per-call timeout in seconds. Falls back to self.timeout.
+            **params: Action parameters
+
+        Returns:
+            Parsed JSON response.
+        """
+        if self.is_api_supported(action) is False:
+            return {
+                "status": "failed",
+                "retcode": 200,
+                "data": None,
+                "message": f"API '{action}' is not supported by this NapCat instance. Check OneBot 11 spec or NapCat extensions.",
+                "wording": f"API '{action}' unsupported",
+            }
+
+        normalized = self._normalize(params)
+        result = self.request(action, json_body=normalized, timeout=timeout)
+
+        # Detect unsupported API responses and cache them
+        if result.get("message", "") == "不支持的Api" or "不支持的Api" in str(result.get("wording", "")):
+            self.mark_api_unsupported(action)
+            result["message"] = f"API '{action}' is not supported by this NapCat instance. Check OneBot 11 spec or NapCat extensions."
+            result["wording"] = f"API '{action}' unsupported"
+        # Map kernel errors to friendly messages
+        raw_msg = result.get("message", "")
+        if raw_msg and result.get("retcode", 0) != 0:
+            friendly = self.friendly_error(raw_msg)
+            if friendly != raw_msg:
+                result["message"] = friendly
+
+        return result
+
+    def _connection_hint(self) -> str:
+        """Generate helpful hint when connection fails."""
+        hints = []
+        # Check if container is running
+        try:
+            import subprocess
+            result = subprocess.run(
+                ["docker", "ps", "--filter", "name=napcat", "--format", "{{.Status}}"],
+                capture_output=True, text=True, timeout=5,
+            )
+            if not result.stdout.strip():
+                hints.append("NapCat Docker container is not running. Start with: docker compose up -d")
+            elif "Exited" in result.stdout:
+                hints.append("NapCat container has exited. Check logs: docker logs napcat")
+        except Exception:
+            pass
+
+        # Check URL
+        if not self.api_url:
+            hints.append("NAPCAT_API_URL not set. Default: http://127.0.0.1:18801")
+
+        # Check if logged in
+        hints.append("Make sure you have logged in via WebUI (http://127.0.0.1:6099/webui)")
+
+        return " | ".join(hints) if hints else "Check NapCat container and login status"

napcat_cli/lib/config.py

@@ -0,0 +1,105 @@
+"""Configuration management for napcat-cli."""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, fields, asdict
+from pathlib import Path
+
+
+def _get_data_dir() -> Path:
+    """Return the data directory, re-computed from env each call."""
+    return Path(os.environ.get("NAPCAT_DATA_DIR", str(Path.home() / ".napcat-data")))
+
+
+class _LazyPath:
+    """Lazy proxy: re-reads NAPCAT_DATA_DIR on each access."""
+    def __truediv__(self, other):
+        return _get_data_dir() / other
+    def __str__(self):
+        return str(_get_data_dir())
+    def __repr__(self):
+        return f"DATA_DIR({_get_data_dir()!s})"
+
+
+DATA_DIR = _LazyPath()
+
+
+@dataclass
+class NapCatConfig:
+    """napcat-cli configuration."""
+    api_url: str = "http://127.0.0.1:18801"
+    token: str = ""
+    self_id: str | None = None
+    webhook_port: int = 18820
+    ws_port: int = 18800
+    http_port: int = 18821
+    wake_on_event: bool = True          # deprecated alias of wake_enabled (back-compat)
+    wake_command: str = ""              # legacy shell escape hatch (used only if no backend configured)
+
+    # --- generic, pluggable agent wake (Hermes is the default preset, not required) ---
+    wake_enabled: bool = True
+    wake_preset: str = "hermes"         # hermes | custom | none
+    wake_primary: str = "auto"          # auto | http | cli   (auto = http if configured+reachable, else cli)
+    wake_session: str = "napcat-qq"     # session name (cli --continue / http session lookup)
+    wake_http_url: str = ""             # e.g. http://127.0.0.1:8642  (hermes preset default)
+    wake_http_key: str = ""             # bearer token (env: NAPCAT_WAKE_HTTP_KEY)
+    wake_http_session_id: str = ""      # explicit session id; else resolved by name via GET /api/sessions
+    wake_cli_command: str = ""          # rendered template; hermes preset fills it
+    wake_debounce_seconds: float = 3.0
+    wake_cooldown_seconds: float = 30.0
+    wake_new_message_idle_seconds: int = 600
+
+    event_dir: str = "events"
+    alert_dir: str = "alerts"
+    log_file: str = "daemon.log"
+    group_trigger_word: str = ""
+    private_trigger: str = "*"
+
+    # skills-fs integration
+    skills_fs_enabled: bool = True
+    skills_fs_binary: str = ""
+    skills_fs_mountpoint: str = ""
+    skills_fs_config: str = ""
+
+    def save(self) -> None:
+        """Save config to file atomically via temp file then rename."""
+        import os
+        data_dir = _get_data_dir()
+        config_file = data_dir / "config.json"
+        tmp_path = config_file.with_suffix(".tmp")
+        tmp_path.write_text(json.dumps(asdict(self), indent=2, ensure_ascii=False))
+        os.replace(str(tmp_path), str(config_file))
+
+    def set(self, key: str, value: str) -> None:
+        """Set a config value by key name."""
+        if hasattr(self, key):
+            attr = getattr(self, key)
+            if isinstance(attr, bool):
+                value = value.lower() in ("true", "1", "yes")
+            elif isinstance(attr, int):
+                value = int(value)
+            setattr(self, key, value)
+        else:
+            raise ValueError(f"Unknown config key: {key}. Available: {', '.join(f.name for f in fields(NapCatConfig))}")
+
+
+def get_config() -> NapCatConfig:
+    """Load config from file or create default."""
+    data_dir = _get_data_dir()
+    config_file = data_dir / "config.json"
+    if config_file.exists():
+        try:
+            data = json.loads(config_file.read_text())
+            return NapCatConfig(**data)
+        except Exception:
+            pass
+    return NapCatConfig()
+
+
+def ensure_dirs() -> None:
+    """Ensure events and alerts directories exist."""
+    cfg = get_config()
+    data_dir = _get_data_dir()
+    (data_dir / cfg.event_dir).mkdir(exist_ok=True)
+    (data_dir / cfg.alert_dir).mkdir(exist_ok=True)

napcat_cli/lib/events.py

@@ -0,0 +1,127 @@
+"""Event storage for NapCat CLI — SQLite backend.
+
+Events and alerts are stored in a SQLite database (napcat_events.db) for
+fast querying, atomic writes, and proper indexing.
+
+The SQLite database is exposed through the skills-fs HTTP provider so agents
+can query it via HTTP.
+
+Usage:
+    reader = EventsReader(data_dir)
+    events = reader.read(limit=20, since=1700000000, event_type="message")
+
+    writer = EventsWriter(data_dir)
+    writer.write_event({"post_type": "message", ...})
+    writer.write_alert("NAPCAT_CLI_NEW_MESSAGE", {"sender_id": 123})
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from .events_sqlite import (
+    clear_alerts,
+    get_connection,
+    get_db_path,
+    read_alerts,
+    read_events,
+    write_alert,
+    write_event,
+)
+
+
+class EventsWriter:
+    """Write events and alerts to SQLite database."""
+
+    def __init__(self, data_dir: Path):
+        self.data_dir = data_dir
+        self.conn = get_connection(data_dir)
+
+    def write_event(self, event: dict[str, Any], event_type: str = "") -> int:
+        """Write an event to the database. Returns the row ID."""
+        return write_event(self.conn, event)
+
+    def write_alert(self, alert_name: str, data: dict[str, Any]) -> int:
+        """Write an alert to the database. Returns the row ID."""
+        return write_alert(self.conn, alert_name, data)
+
+    def clear_alert(self, name: str) -> bool:
+        """Clear a specific alert."""
+        count = clear_alerts(self.conn, name)
+        return count > 0
+
+    def clear_all_alerts(self) -> int:
+        """Clear all alerts. Returns count cleared."""
+        return clear_alerts(self.conn)
+
+    def close(self) -> None:
+        """Close the database connection."""
+        self.conn.close()
+
+
+class EventsReader:
+    """Read events from SQLite database."""
+
+    def __init__(self, data_dir: Path):
+        self.data_dir = data_dir
+        self.db_path = get_db_path(data_dir)
+        self._conn: sqlite3.Connection | None = None
+
+    def _get_conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self._conn = get_connection(self.data_dir)
+        return self._conn
+
+    def read(
+        self,
+        limit: int = 50,
+        event_type: str | None = None,
+        since: int | None = None,
+        post_type: str | None = None,
+        group_id: int | None = None,
+        user_id: int | None = None,
+        keyword: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Read events from SQLite, newest first.
+
+        Args:
+            limit: Maximum number of events to return.
+            event_type: Filter by event type (e.g., "message", "heartbeat").
+            since: Only include events with timestamp >= since.
+            post_type: Filter by post_type (e.g., "message", "notice").
+            group_id: Filter by group_id.
+            user_id: Filter by user_id or sender_id.
+            keyword: Filter by keyword in raw_json (LIKE query).
+        """
+        conn = self._get_conn()
+        return read_events(
+            conn,
+            limit=limit,
+            event_type=event_type,
+            since=since,
+            post_type=post_type,
+            group_id=group_id,
+            user_id=user_id,
+            keyword=keyword,
+        )
+
+    def read_alerts(
+        self,
+        name: str | None = None,
+        limit: int = 50,
+    ) -> list[dict[str, Any]]:
+        """Read alerts from the database."""
+        conn = self._get_conn()
+        return read_alerts(conn, name=name, limit=limit)
+
+    def get_count(self) -> int:
+        """Get total event count."""
+        from .events_sqlite import get_event_count
+        conn = self._get_conn()
+        return get_event_count(conn)
+
+    def close(self) -> None:
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None