Add internal RevOps export API

docs/automations/qrmaster-internal-revops-export.md

@@ -0,0 +1,131 @@
+# QR Master Internal RevOps Export API
+
+This endpoint exposes read-only QR Master admin/product data for trusted automations such as Hermes cron jobs.
+
+## Endpoint
+
+```http
+GET /api/internal/revops-export
+Authorization: Bearer <INTERNAL_API_SECRET>
+```
+
+The endpoint accepts `INTERNAL_API_SECRET` first, with `CRON_SECRET` as a fallback for compatibility.
+
+## Purpose
+
+QR Master only exports structured data. It does **not** perform AI analysis, web research, email drafting, or lead outreach.
+
+Hermes is responsible for:
+
+- calling this API on a schedule,
+- researching public websites/domains with its tools,
+- deciding which leads are worth manual outreach,
+- drafting personalized emails,
+- sending Timo an internal briefing,
+- never auto-sending messages to QR Master users.
+
+## Query Parameters
+
+| Parameter | Example | Notes |
+|---|---|---|
+| `range` | `24h`, `7d`, `30d`, `all` | Defaults to `24h`. |
+| `from` | `2026-06-30T00:00:00Z` | Optional explicit start. Overrides `range`. |
+| `to` | `2026-07-01T00:00:00Z` | Optional explicit end. Defaults to now if `from` is set. |
+| `limit` | `100` | User/lead limit. Defaults to 100, max 500. |
+| `allUsers` | `true` | Exports all users up to `limit`; otherwise exports users active/relevant in range. |
+
+## Example Calls
+
+Daily Hermes lead research context:
+
+```bash
+curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
+  "https://www.qrmaster.net/api/internal/revops-export?range=24h&limit=100"
+```
+
+Weekly progress context:
+
+```bash
+curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
+  "https://www.qrmaster.net/api/internal/revops-export?range=7d&limit=200"
+```
+
+Local development:
+
+```bash
+curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
+  "http://localhost:3050/api/internal/revops-export?range=24h"
+```
+
+## Response Shape
+
+Top-level fields:
+
+```json
+{
+  "ok": true,
+  "generatedAt": "2026-07-01T18:00:00.000Z",
+  "endpoint": "/api/internal/revops-export",
+  "range": {
+    "preset": "24h",
+    "from": "2026-06-30T18:00:00.000Z",
+    "to": "2026-07-01T18:00:00.000Z"
+  },
+  "overview": {},
+  "breakdowns": {},
+  "users": [],
+  "leads": [],
+  "newsletterSubscriptions": []
+}
+```
+
+Each exported user includes:
+
+- identity: `id`, `name`, `email`, `emailDomain`, `createdAt`, `updatedAt`
+- plan/subscription flags
+- attribution fields
+- onboarding fields
+- lifecycle scores and timestamps
+- aggregate stats
+- QR codes, content, public path, and scan summaries
+- integrations
+- recent lifecycle logs
+
+## Safety Rules for Hermes Jobs
+
+Hermes should treat this API as internal source data and follow these rules:
+
+1. Do not send outreach emails directly to leads.
+2. Send only an internal briefing/draft pack to Timo.
+3. Use public web research only when it improves personalization.
+4. Do not tell leads they were researched.
+5. Avoid creepy language; frame personalization around their QR Master activity and likely workflow.
+6. Never expose API secrets or raw sensitive internals in the briefing.
+7. Prefer business-use signals: QR content type, destination, scans, onboarding use case, domain, company website, landing path.
+
+## Suggested Hermes Cron Jobs
+
+### Daily QR Master Lead Research
+
+Schedule: daily, evening.
+
+Prompt should:
+
+1. call `/api/internal/revops-export?range=24h`,
+2. identify promising leads,
+3. research public company/domain signals,
+4. draft personalized outreach emails from Timo,
+5. send Timo an internal email briefing,
+6. never send emails to leads.
+
+### Weekly QR Master Progress Review
+
+Schedule: Sunday evening.
+
+Prompt should:
+
+1. call `/api/internal/revops-export?range=7d`,
+2. summarize users, QR creation, scans, activations, paid/upgrades,
+3. identify bottlenecks,
+4. suggest next-week goals,
+5. email Timo the review.