Phase 3: Scheduled metric sync (PostHog first, HubSpot + Common Room after validation)

[tessak22]

Overview

The primary workflow for pulling metrics from external tools (PostHog, HubSpot, Common Room) into Quiver is via MCP — the user asks Claude to fetch data from those tools' MCP servers and log it via the Quiver MCP log_performance tool. No OAuth connectors, no credentials stored in Quiver, no integration infrastructure to build.

This issue covers the one thing that genuinely benefits from living in the app itself: a scheduled sync mechanism for teams who want metrics to flow into Quiver automatically, without initiating a conversation.

---

The MCP-first workflow (no build required)

This is already possible once issue #26 (MCP server) ships. No code needed here for this path.

Example:

"Pull last week's PostHog funnel metrics for the Developer Outreach campaign and log them in Quiver"

Claude calls the PostHog MCP to fetch the data, then calls the Quiver MCP log_performance tool to save it. The result appears in the performance log immediately.

This works for any tool the user has connected as an MCP server. It is intentional — the user decides when to log, which keeps performance data meaningful rather than noisy.

---

What this issue actually builds: scheduled sync

For teams who want metrics to flow in automatically on a recurring basis without initiating a conversation, Quiver needs a lightweight scheduled sync system.

How it works

Admins define sync rules in Settings. Each rule is:

• A source (PostHog event, HubSpot email metric, Common Room signal)
• A target campaign or artifact in Quiver
• A metric name to log (e.g. signups, open_rate, community_members)
• A schedule (daily or weekly)

At the scheduled time, a cron job runs the sync, fetches the metric, and creates a PerformanceLog entry. The log entry is tagged recordedBy: 'scheduled_sync' and includes the source in qualitativeNotes.

This is explicitly Phase 3

Per SPEC.md out-of-scope list: "Direct API integrations for performance data (PostHog, Common Room, HubSpot) — manual entry in v1, integrations are Phase 3."

Do not build this until:

1. The MCP workflow (MCP server: full Quiver API over Model Context Protocol #26) is live and being used
2. There is real evidence that manual/conversational logging is insufficient for the team's needs
3. At least one integration source has been validated as worth the maintenance cost

---

Scope when ready to build

Settings UI

• Sync rules list: source, target, metric name, schedule, last synced, status
• Add rule form: source type selector, credential input (API key only — no OAuth in v1), target campaign/artifact selector, metric name, schedule
• Manual "Sync now" button per rule
• Enable/disable toggle per rule
• Credentials stored encrypted in DB, never exposed in UI after entry

Sync engine

• Cron job (Vercel cron or Railway scheduler depending on deploy target)
• One handler per source type: lib/sync/posthog.ts, lib/sync/hubspot.ts, lib/sync/common-room.ts
• Each handler: fetch metric → call createPerformanceLog() → return result
• Graceful failure: if a sync fails, log the error and continue — do not block other rules
• Sync log: record of every sync attempt (rule, timestamp, success/failure, value fetched)

Supported sources (v1 of this feature)

Start with one source only. Validate before adding more.

• PostHog — event count for a named event, over a date range. Simplest API, most likely to be used first.

Add HubSpot and Common Room only after PostHog sync is validated in production.

DB additions

Two new tables:

• sync_rules — rule config (source type, credentials encrypted, target, metric name, schedule, enabled)
• sync_logs — record of every sync attempt

---

Acceptance criteria (when this is prioritized)

• Settings page shows sync rules list with add/edit/delete
• Credentials stored encrypted, never returned to client after save
• PostHog sync handler implemented in lib/sync/posthog.ts
• Cron job triggers sync on schedule
• Failed syncs logged, do not throw or block other rules
• Manual "Sync now" button works per rule
• Sync creates PerformanceLog entry with recordedBy: 'scheduled_sync'
• Sync log visible in settings so admin can see what ran and when
• HubSpot and Common Room sources added only after PostHog is validated

---

Priority

Do not build until after #26 (MCP server) is live and the conversational workflow has been used in practice. The MCP path covers the vast majority of use cases without any integration infrastructure. Only build scheduled sync if there is clear evidence that automatic pulls are needed.

Original issue scope (OAuth connectors, full API integrations, auto-mapping) is replaced by this approach. The MCP-first workflow is the v1 answer.