Client Reporting Automation

Pull metrics from multiple sources, generate branded reports, and auto-deliver to clients. Built for agencies and freelancers who need consistent, professional reporting without manual work.

Setup

Dependencies

pip3 install requests jinja2

API Keys (configure in config.json)

• Google Analytics 4 — GA4_PROPERTY_ID + service account key
• Google Search Console — service account key (see seo-audit-suite references)
• Social platforms — same credentials as social-media-autopilot skill
• SendGrid — for email delivery (SENDGRID_API_KEY)

Workspace

client-reports/
├── config.json           # Global settings, API keys
├── clients/              # Per-client configuration
│   └── client-name/
│       ├── config.json   # Client-specific settings (property IDs, branding)
│       ├── reports/      # Generated reports
│       └── data/         # Cached metrics data
├── templates/            # Report templates (Jinja2 HTML)
└── schedules.json        # Automated delivery schedule

Run scripts/init-workspace.sh to create this structure.

Core Workflows

1. Add a Client

scripts/add-client.sh --name "acme-corp" --domain "acme.com" --email "[email protected]"

Creates client directory with config template. Edit clients/acme-corp/config.json to add:

• GA4 property ID
• Search Console site URL
• Social media handles
• Branding (logo URL, brand colors)
• Report preferences (metrics to include, frequency)

2. Pull Metrics

Fetch fresh data for a client:

scripts/pull-metrics.sh --client "acme-corp"                    # All sources
scripts/pull-metrics.sh --client "acme-corp" --source ga4       # Google Analytics only
scripts/pull-metrics.sh --client "acme-corp" --source gsc       # Search Console only
scripts/pull-metrics.sh --client "acme-corp" --source social    # Social metrics
scripts/pull-metrics.sh --client "acme-corp" --period 30d       # Last 30 days

Data sources and metrics:

Google Analytics 4:

• Sessions, users, new users, bounce rate
• Top pages by views
• Traffic sources breakdown
• Conversion events
• Device/browser breakdown

Google Search Console:

• Total clicks, impressions, CTR, avg position
• Top queries by clicks
• Top pages by impressions
• Position changes vs previous period

Social Media:

• Followers/following changes
• Post engagement (likes, shares, comments)
• Top performing posts
• Reach/impressions

3. Generate Reports

scripts/generate-report.sh --client "acme-corp" --type monthly
scripts/generate-report.sh --client "acme-corp" --type weekly --format html
scripts/generate-report.sh --client "acme-corp" --type custom --metrics "traffic,rankings,social"

Report types:

• weekly — 7-day snapshot with week-over-week changes
• monthly — 30-day deep dive with month-over-month trends
• quarterly — 90-day strategic overview
• custom — pick specific metrics

Output formats:

• Markdown — default, good for Slack/email
• HTML — branded, professional, email-ready
• PDF — via HTML-to-PDF conversion (requires wkhtmltopdf or similar)

4. Auto-Deliver Reports

scripts/deliver-report.sh --client "acme-corp" --latest         # Send most recent
scripts/deliver-report.sh --client "acme-corp" --via email      # Email delivery
scripts/deliver-report.sh --client "acme-corp" --via slack      # Slack webhook

5. Schedule Recurring Reports

Configure in schedules.json:

{
  "schedules": [
    {
      "client": "acme-corp",
      "type": "weekly",
      "day": "monday",
      "time": "09:00",
      "timezone": "America/Los_Angeles",
      "deliver_via": "email",
      "enabled": true
    },
    {
      "client": "acme-corp",
      "type": "monthly",
      "day_of_month": 1,
      "time": "09:00",
      "timezone": "America/Los_Angeles",
      "deliver_via": "email",
      "enabled": true
    }
  ]
}

Use with OpenClaw cron to automate: check schedules daily, generate and deliver due reports.

6. KPI Dashboard

Quick terminal dashboard for any client:

scripts/dashboard.sh --client "acme-corp"

Shows current period vs previous: traffic, rankings, social growth, conversions.

Report Template System

Templates use Jinja2 and live in templates/:

\x3C!-- templates/monthly.html -->
\x3Chtml>
\x3Chead>\x3Cstyle>/* brand styles */\x3C/style>\x3C/head>
\x3Cbody>
  \x3Ch1>Monthly Report — {{ client.name }}\x3C/h1>
  \x3Cp>{{ period.start }} to {{ period.end }}\x3C/p>
  
  \x3Ch2>Traffic Overview\x3C/h2>
  \x3Ctable>
    \x3Ctr>\x3Ctd>Sessions\x3C/td>\x3Ctd>{{ ga4.sessions }}\x3C/td>\x3Ctd>{{ ga4.sessions_change }}%\x3C/td>\x3C/tr>
    \x3Ctr>\x3Ctd>Users\x3C/td>\x3Ctd>{{ ga4.users }}\x3C/td>\x3Ctd>{{ ga4.users_change }}%\x3C/td>\x3C/tr>
  \x3C/table>
  
  \x3Ch2>Search Performance\x3C/h2>
  \x3C!-- ... -->
\x3C/body>
\x3C/html>

Customize templates per client by placing overrides in clients/\x3Cname>/templates/.

Cron Integration

• Daily: Pull fresh metrics for all active clients
• Weekly: Generate and deliver weekly reports (Monday AM)
• Monthly: Generate and deliver monthly reports (1st of month)
• Quarterly: Generate quarterly reviews

References

• references/ga4-setup.md — Google Analytics 4 API setup and available metrics
• references/report-customization.md — How to customize templates and metrics