Metadata-Version: 2.4
Name: dex-bot-claude
Version: 3.0.0
Summary: Ops automation system for web property monitoring, GA4 analytics, and scheduled reporting with Telegram notifications
Author: redredchen01
License-Expression: MIT
Project-URL: Repository, https://github.com/redredchen01/dex-bot-automation
Keywords: automation,monitoring,ga4,telegram,ops
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# DEX Bot Automation v3.0

Ops automation system for managing and monitoring web properties. Runs 15+ scheduled tasks via macOS launchd (or Docker), covering site health checks, GA4 analytics, competitor tracking, SSL/domain monitoring, and daily/weekly reporting — all with Telegram push notifications.

## Features

- **Site Health Monitoring** — every 5 min checks with alert silencing and recovery notifications
- **GA4 Analytics** — daily/weekly/monthly reports, real-time anomaly alerts (spike/drop detection)
- **Lighthouse Audits** — automated performance scoring with CSV history tracking
- **Competitor Watch** — sitemap diffing against competitors with false-positive filtering
- **SSL & Domain Expiry** — Node.js TLS-based cert checks + domain countdown
- **Broken Link Scanner** — weekly crawl with concurrent link validation
- **Cross-Site Funnel** — traffic funnel analysis across properties
- **Daily/Weekly Reports** — structured ops reports with strict submission standards
- **Morning Briefing** — consolidated daily summary pushed before standup
- **Dashboard** — hourly auto-generated HTML dashboard integrating 5 data sources
- **Log Rotation** — 7-day cleanup + 1MB truncation

## v3.0 Highlights

- **Security**: All shell command injection vectors eliminated (`execFileSync` + args arrays, Node `tls` module)
- **Shared Modules**: `lib/` with state management, date utils, formatting, CSV, GA4 helpers
- **Testing**: 54 unit tests via Vitest + ESLint + GitHub Actions CI
- **Structured Logging**: JSON log output with level filtering (`lib/logger.mjs`)
- **Resilience**: Retry with exponential backoff + circuit breaker pattern
- **Config**: Externalized to `config/default.json` with env var overrides
- **Docker**: Optional containerized deployment
- **TypeScript Ready**: `tsconfig.json` with `allowJs` for incremental migration

## Monitored Sites

| Site | URL |
|------|-----|
| 小黃書 | xhslink.com |
| 51漫畫 | 51acgs.com |

## Tech Stack

- **Runtime**: Node.js (ESM)
- **Analytics**: Google Analytics Data API (`@google-analytics/data`)
- **Google APIs**: `googleapis` (Gmail, Sheets, etc.)
- **Notifications**: Telegram Bot API
- **Scheduling**: macOS launchd (15 plist configs in `launchd/`)
- **AI Agents**: Claude Code subagents + external AI dispatch (Gemini, Codex, OpenCode)

## Project Structure

```
├── config/default.json      # Externalized config (sites, thresholds, email)
├── config.mjs               # Config loader with env var overrides
├── automation-cron.sh        # Unified cron entry point for all tasks
├── ai-dispatch.sh            # Multi-AI agent dispatcher (portable timeout)
├── team-dispatch.sh          # Multi-agent parallel workflow
│
├── lib/                      # Shared modules (v3.0)
│   ├── state.mjs             # State management factory
│   ├── date.mjs              # Timezone-aware date utilities
│   ├── format.mjs            # Text formatting (fmtNum, pct, bar, etc.)
│   ├── csv.mjs               # CSV read/write/dedup
│   ├── ga4-helpers.mjs       # GA4 metric extraction helpers
│   ├── logger.mjs            # Structured JSON logging
│   ├── retry.mjs             # Retry with exponential backoff
│   └── circuit-breaker.mjs   # Per-service circuit breaker
│
├── tests/lib/                # Unit tests (54 tests)
├── .github/workflows/ci.yml  # GitHub Actions CI
├── vitest.config.mjs         # Test configuration
├── eslint.config.mjs         # Lint configuration
├── tsconfig.json             # TypeScript (incremental migration)
├── Dockerfile                # Optional container deployment
│
├── site-health.mjs           # Site uptime monitoring
├── ga4-alert.mjs             # Real-time GA4 anomaly detection
├── ga4-daily-report.mjs      # Daily GA4 analytics report
├── ...                       # (15+ automation scripts)
│
├── launchd/                  # macOS launchd plist configs (15 schedules)
└── .claude/agents/           # Claude Code subagent definitions
```

## Setup

```bash
# Install dependencies
npm install

# Copy and edit environment config
cp .env.example .env

# Required: GA4 service account key (not committed)
# Place your key file as: openclaw-ga4-488308-b099b607405b.json

# Required: Telegram bot config
# Create hooks-config.json with your bot token and chat ID

# Install launchd schedules (macOS)
cp launchd/*.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.dex.*.plist

# Or run with Docker
docker compose up -d
```

## Development

```bash
npm test          # Run 54 unit tests
npm run lint      # ESLint check
npm run smoke     # Syntax validation for all scripts
```

## Usage

Run any task manually via the unified entry point:

```bash
./automation-cron.sh <task-name>
```

Available tasks: `health`, `ga4-alert`, `ga4-daily`, `ga4-weekly`, `ga4-monthly`, `lighthouse`, `competitor`, `ssl`, `morning-briefing`, `daily-report`, `ops-report`, `weekend-review`, `funnel`, `broken-links`, `dashboard`, `log-rotate`, `backup`, `smoke-test`

### AI Agent Dispatch

```bash
# Single agent
./ai-dispatch.sh <agent> "<prompt>" [timeout]

# All agents in parallel
./ai-dispatch.sh all "<prompt>"

# Smart routing
./ai-dispatch.sh best "<prompt>"

# Multi-agent code review
./team-dispatch.sh multi-review
```

## Schedule Overview

| Schedule | Frequency | Task |
|----------|-----------|------|
| Site Health | Weekdays every 5 min | Uptime monitoring |
| GA4 Alert | Weekdays hourly (after 09:00) | Anomaly detection |
| GA4 Daily | Weekdays 09:00 | Daily analytics |
| GA4 Weekly | Monday 09:30 | Weekly insights |
| Morning Briefing | Weekdays 09:50 | Daily summary |
| Daily Report | Weekdays 17:50 | Work report |
| Lighthouse | Weekdays 06:00 | Performance audit |
| Competitor | Weekdays 07:00 | Competitor tracking |
| SSL Check | Weekdays 08:00 | SSL/domain expiry |
| Dashboard | Hourly | HTML dashboard |
| Log Rotate | Daily 03:00 | Log cleanup |
| Broken Links | Wednesday 04:00 | Link validation |
| Funnel | Monday 10:00 | Traffic funnel |
| Ops Report | Friday 18:00 | Weekly ops summary |
| Weekend Review | Monday 08:00 | Weekend digest |

All weekday-only tasks are silenced on weekends (both at plist level and in-script `skipWeekend()`).

## License

MIT
