basecamp-activity

name	basecamp-activity
description	Fetch Basecamp project or person activity into day-cached JSON atoms. Uses the Basecamp API with pagination and rate-limit backoff. Part of the recap plugin's activity fetcher pipeline.
triggers	["/recap:basecamp-activity","basecamp activity","basecamp project activity"]

Basecamp Activity Fetcher

Fetch Basecamp activity events into per-day cached JSON atoms. Supports two scopes:

• Project-scoped (--project): all events in a Basecamp project
• Person-scoped (--person): all activity by a specific user

Caches at ~/.cache/recap/basecamp-project/{id}/{YYYY-MM-DD}/activity.json or ~/.cache/recap/basecamp-person/{slug}/{YYYY-MM-DD}/activity.json.

Invocation

/recap:basecamp-activity --project 43483623 --since 2026-03-23
/recap:basecamp-activity --project 43483623 --since 2026-03-23 --until 2026-03-30 --reuse
/recap:basecamp-activity --person "Jeremy Daer" --since 2026-03-23

Contract

• Idempotent: same input produces same output, safe to re-run
• Day-cached: one JSON file per scope per day
• --reuse: skip fetch if cache exists and is marked complete
• Rate-limit aware: exponential backoff on 429 responses

Quick Run

# 1. Validate auth
basecamp auth status | jq -e '.data.authenticated' || { echo "Run: basecamp auth login"; exit 1; }

# 2. Determine date range
SINCE=$(date -d "7 days ago" +%Y-%m-%d)
UNTIL=$(date +%Y-%m-%d)

# 3. Run the fetcher (project-scoped)
"$SKILL_DIR/scripts/basecamp-activity.sh" \
  --project 43483623 --since "$SINCE" --until "$UNTIL"

# 4. Verify cache
ls ~/.cache/recap/basecamp-project/43483623/
cat ~/.cache/recap/basecamp-project/43483623/$SINCE/activity.json | jq '.metadata'

Where $SKILL_DIR = directory containing this SKILL.md.

Output Format

Each activity.json contains:

{
  "scope": "project 43483623",
  "date": "2026-03-24",
  "events": [
    {
      "id": 123456,
      "kind": "message_created",
      "created_at": "2026-03-24T14:30:00Z",
      "creator": { "id": 789, "name": "Jeremy" },
      "title": "Weekly update",
      "url": "https://3.basecampapi.com/..."
    }
  ],
  "metadata": { "complete": true, "count": 5 }
}

Arguments

Argument	Required	Description
--project	One of project/person	Basecamp project ID
--person	One of project/person	Person name or ID (passed to basecamp timeline --person)
--since	Yes	Start date (YYYY-MM-DD)
--until	No	End date (default: today)
--reuse	No	Skip fetch if cache exists and is complete

Cache Structure

~/.cache/recap/basecamp-project/
  43483623/
    2026-03-24/activity.json
    2026-03-25/activity.json

Prerequisites

• basecamp CLI installed and authenticated (basecamp auth login)
• jq for JSON parsing
• curl for API calls

Failure Modes

Symptom	Cause	Fix
"basecamp not authenticated"	Token expired	basecamp auth login
"account not configured"	Missing config	basecamp config setup
Rate limit	Too many API calls	Script retries automatically with backoff
Empty activity	No events in range	Expected — empty days are cached as complete
HTTP 404	Wrong project ID	Verify project ID in Basecamp URL