client-reporting

name

client-reporting

description

Automated client reporting for agencies and freelancers using OpenClaw. Pull data from Google Analytics, Google Search Console, social media platforms, and custom sources to generate branded weekly/monthly reports. Auto-deliver via email or Slack. Use when: (1) generating client reports, (2) pulling analytics data for reporting, (3) automating recurring reports, (4) creating branded PDF or HTML reports, (5) scheduling report delivery, or (6) tracking client KPIs over time.

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 "[e-mail]"

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": 
       
    
  

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/:

<!-- templates/monthly.html -->
<html>
<head><style>/* brand styles */</style></head>
<body>
  <h1>Monthly Report — {{ client.name }}</h1>
  <p>{{ period.start }} to {{ period.end }}</p>
  
  <h2>Traffic Overview</h2>
  <table>
    <tr><td>Sessions</td><td>{{ ga4.sessions }}</td><td>{{ ga4.sessions_change }}%</td></tr>
    <tr><td>Users</td><td>{{ ga4.users }}</td><td>{{ ga4.users_change }}%</td></tr>
  </table>
  
  <>Search Performance
  

Customize templates per client by placing overrides in clients/<name>/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