feat(reporting): build Stage 09 reporting foundations

.agents/CLAUDE.md

@@ -93,7 +93,7 @@ Veerify is a feedback management and verification platform built with **Nuxt 3**
 
 ### Prerequisites
 
-- Node.js 18+
+- Node.js 22.12+
 - Yarn
 - Docker (for local PostgreSQL + Mailpit)
 

.dockerignore

@@ -0,0 +1,26 @@
+node_modules
+.output
+.data
+.nuxt
+.nitro
+.cache
+dist
+.git
+.github
+.vscode
+.idea
+.fleet
+.claude
+.agents
+.cursor
+docs
+playwright-report
+test-results
+tests
+*.log
+.env
+.env.*
+!.env.example
+.DS_Store
+README.md
+export-*.csv

.env.example

@@ -28,8 +28,15 @@ APP_DOMAIN=localhost
 # Dashboard domain (used by login/signup links from public boards)
 # Defaults to app.<APP_DOMAIN> when omitted in non-local environments.
 APP_DASHBOARD_DOMAIN=localhost
+# Optional public URL used in outbound CSAT rating links. Set this to the
+# customer-facing HTTPS origin in production; it must be an absolute URL.
+APP_URL= # Optional public origin; leave empty to fall back to BETTER_AUTH_URL
 # Optional: "self-hosted" or "cloud". When omitted, auto-detected from platform env vars.
 APP_DEPLOYMENT_MODE=self-hosted
+# Optional, development only. Comma-separated extra Host headers the Vite dev server
+# will accept, for reaching `yarn dev` through an HTTPS reverse proxy such as
+# Tailscale Serve. Leave empty unless you use one. Example: dev.my-tailnet.ts.net
+NUXT_DEV_ALLOWED_HOSTS=
 
 # CNAME target for custom domain setup (point users' CNAMEs here)
 CNAME_TARGET=cname.veerify.io
@@ -44,6 +51,46 @@ VERCEL_PROJECT_ID=
 VERCEL_TEAM_ID=
 VERCEL_TEAM_SLUG=
 
+# Inbound support email provider. Webhook-only: there is no IMAP polling
+# (delta D-29). The [provider] segment of /api/support/inbound/[provider]
+# selects the driver per request; this names the deployment's default.
+SUPPORT_CHANNEL_PROVIDER=postmark
+
+# Postmark does NOT sign inbound webhooks - its documented protection is HTTP
+# Basic Auth in the webhook URL plus IP allowlisting. Set both, then register
+# https://user:password@your-host/api/support/inbound/postmark with Postmark.
+# Inbound mail is rejected while these are unset; an empty credential must
+# never mean "accept anything".
+SUPPORT_POSTMARK_WEBHOOK_USER=
+SUPPORT_POSTMARK_WEBHOOK_PASSWORD=
+
+# Required when using Mailgun. This is the webhook signing key (not the API
+# key); Mailgun signs HMAC-SHA256(timestamp + token) with it.
+SUPPORT_MAILGUN_SIGNING_KEY=
+
+# OPTIONAL, Stage 04. Used only to check whether an inbox's From address sits
+# on a domain the provider will actually accept, so /support/settings can warn
+# before mail silently fails at send time. Leave unset and the check reports
+# "cannot verify" rather than a false warning - nothing else is affected.
+#
+# Postmark: this is the ACCOUNT token, not a server token. The /domains
+# endpoint is account-level and a server token returns 401 there.
+SUPPORT_POSTMARK_ACCOUNT_TOKEN=
+# Non-secret deployment account identifier persisted with outbound deliveries.
+# MUST equal the value the provider reports on its own delivery webhooks, or the
+# delivery-correlation fallback can never match: for Postmark that is the numeric
+# `ServerID`. The primary correlation path uses our own metadata key and works
+# regardless, but the fallback is the only defence when a provider drops that
+# metadata on an event. Unverified against a live account - see
+# docs/plans/2026-08-11-support-platform/stage-01-04-provider-checklist.md.
+SUPPORT_POSTMARK_ACCOUNT_KEY=
+# Mailgun: the private API key. Set the base URL only for EU accounts
+# (https://api.eu.mailgun.net).
+SUPPORT_MAILGUN_API_KEY=
+# As above: must equal what Mailgun reports on its webhooks, i.e. the sending domain.
+SUPPORT_MAILGUN_ACCOUNT_KEY=
+SUPPORT_MAILGUN_API_BASE_URL=
+
 
 # SMTP Configuration for nodemailer
 SMTP_HOST=localhost
@@ -80,7 +127,41 @@ STORAGE_FORCE_PATH_STYLE=false
 
 # Optional public base URL for storage object links (for CDN/custom host)
 STORAGE_PUBLIC_BASE_URL=
+# Keep proxy-required unless your S3-compatible target demonstrably enforces
+# the signed Content-Length. Accepted value: content-length-enforced.
+STORAGE_DIRECT_UPLOAD_CONSTRAINTS=proxy-required
 
 # Upload token signing secret (REQUIRED — generate a random secret, e.g. `openssl rand -base64 32`)
 # The server will refuse to start if this is not set.
 UPLOAD_TOKEN_SECRET=
+
+# --- Realtime / Redis -------------------------------------------------------
+# Redis connection string. Written against the Redis wire protocol, so any
+# provider works: Upstash on cloud, or the `valkey` service in docker-compose
+# when self-hosting. Leave empty to run single-instance with in-memory drivers.
+# Example: redis://localhost:6379  or  rediss://user:pass@host:6379
+REDIS_URL=
+
+# Realtime transport driver: `redis` | `memory`.
+# Unset infers `redis` when REDIS_URL is set, otherwise `memory`.
+# `memory` is single-instance ONLY — events do not cross app instances.
+REALTIME_DRIVER=
+
+# Rate limiter backing store: `redis` | `memory`.
+# Same inference rule as REALTIME_DRIVER. `memory` does not enforce limits
+# across instances. Shares the REDIS_URL connection; adds no extra socket.
+RATE_LIMIT_STORE=
+
+# --- Scheduled tasks --------------------------------------------------------
+# Shared secret for Vercel Cron HTTP endpoints under /api/cron/*.
+# REQUIRED on cloud deployments: the endpoints fail closed, so an unset secret
+# means every scheduled task returns 401 and silently never runs.
+# Not needed when self-hosting, where Nitro runs tasks in-process.
+# Generate with: openssl rand -base64 32
+CRON_SECRET=
+
+# --- Self-hosted deployment (docker-compose.yml) -----------------------------
+# Public hostname serving uploaded assets through the Caddy reverse proxy.
+# Required by docker-compose.yml and the Caddyfile when self-hosting.
+# Example: assets.example.com
+STORAGE_DOMAIN=

.gitattributes

@@ -0,0 +1,4 @@
+# Shell scripts must keep LF line endings regardless of core.autocrlf so
+# they run correctly inside Linux containers (a CRLF shebang breaks `/bin/sh`).
+*.sh text eol=lf
+Caddyfile text eol=lf

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
 
       - uses: actions/setup-node@v5
         with:
-          node-version: '20'
+          node-version: '22'
           cache: yarn
 
       - run: yarn install --frozen-lockfile
@@ -36,7 +36,7 @@ jobs:
 
       - uses: actions/setup-node@v5
         with:
-          node-version: '20'
+          node-version: '22'
           cache: yarn
 
       - run: yarn install --frozen-lockfile
@@ -53,7 +53,7 @@ jobs:
 
       - uses: actions/setup-node@v5
         with:
-          node-version: '20'
+          node-version: '22'
           cache: yarn
 
       - run: yarn install --frozen-lockfile
@@ -69,15 +69,12 @@ jobs:
 
       - uses: actions/setup-node@v5
         with:
-          node-version: '20'
+          node-version: '22'
           cache: yarn
 
       - run: yarn install --frozen-lockfile
 
-        # Run nuxt build directly (not `yarn build`) to skip the
-        # postbuild lifecycle hook, which runs db migrations and
-        # requires a live PostgreSQL connection.
-      - run: npx nuxt build
+      - run: yarn build
 
   e2e:
     name: E2E (Playwright)
@@ -108,13 +105,19 @@ jobs:
       PGPASSWORD: veerifypassword
       PGDATABASE: veerifydb
       BETTER_AUTH_URL: http://localhost:4173
+      UPLOAD_TOKEN_SECRET: playwright-e2e-upload-secret
+      # The OAuth test only validates the generated GitHub authorization URL;
+      # these placeholder credentials keep the provider enabled without using
+      # a real GitHub application or secret in CI.
+      GITHUB_CLIENT_ID: playwright-e2e-github-client
+      GITHUB_CLIENT_SECRET: playwright-e2e-github-secret
       PLAYWRIGHT_SKIP_IS_FAILURE: '1'
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-node@v5
         with:
-          node-version: '20'
+          node-version: '22'
           cache: yarn
 
       - run: yarn install --frozen-lockfile
@@ -123,7 +126,7 @@ jobs:
         run: npx playwright install --with-deps chromium
 
       - name: Run migrations
-        run: yarn db:migrate
+        run: yarn db:migrate:deploy
 
       - name: Seed test data
         run: yarn db:seed:e2e

.github/workflows/neon.yml

@@ -26,7 +26,7 @@ jobs:
     name: Create Neon Branch
     outputs:
       db_url: ${{ steps.create_neon_branch.outputs.db_url }}
-      db_url_with_pooler: ${{ steps.create_neon_branch.outputs.db_url_with_pooler }}
+      db_url_pooled: ${{ steps.create_neon_branch.outputs.db_url_pooled }}
     needs: setup
     if: |
       github.event_name == 'pull_request' && (
@@ -57,14 +57,39 @@ jobs:
       || github.event.action == 'reopened')
     runs-on: ubuntu-latest
     env:
-      DATABASE_URL: ${{ needs.create_neon_branch.outputs.db_url_with_pooler }}
       BETTER_AUTH_URL: http://localhost:4173
+      UPLOAD_TOKEN_SECRET: playwright-e2e-upload-secret
+      # The OAuth test only validates the generated GitHub authorization URL;
+      # these placeholder credentials keep the provider enabled without using
+      # a real GitHub application or secret in CI.
+      GITHUB_CLIENT_ID: playwright-e2e-github-client
+      GITHUB_CLIENT_SECRET: playwright-e2e-github-secret
     steps:
       - uses: actions/checkout@v4
 
+      # Job outputs containing connection strings are treated as secrets by
+      # GitHub and are not reliably forwarded between jobs. Resolve the
+      # already-created branch again in this job so its pooled URL is available
+      # to the migration, seed, and Playwright steps without crossing a job
+      # boundary.
+      - name: Resolve Neon branch connection
+        id: resolve_neon_branch
+        uses: neondatabase/create-branch-action@v6
+        with:
+          project_id: ${{ vars.NEON_PROJECT_ID }}
+          branch_name: preview/pr-${{ github.event.number }}-${{ needs.setup.outputs.branch }}
+          api_key: ${{ secrets.NEON_API_KEY }}
+          role: neondb_owner
+          database: neondb
+          ssl: require
+          suspend_timeout: 0
+
+      - name: Export Neon database URL
+        run: echo "DATABASE_URL=${{ steps.resolve_neon_branch.outputs.db_url_pooled }}" >> "$GITHUB_ENV"
+
       - uses: actions/setup-node@v5
         with:
-          node-version: '20'
+          node-version: '22'
           cache: yarn
 
       - run: yarn install --frozen-lockfile
@@ -103,15 +128,15 @@ jobs:
   # You may want to do something with the new branch, such as run migrations, run tests
   # on it, or send the connection details to a hosting platform environment.
   # The branch DATABASE_URL is available to you via:
-  # "${{ steps.create_neon_branch.outputs.db_url_with_pooler }}".
+  # "${{ steps.create_neon_branch.outputs.db_url_pooled }}".
   # It's important you don't log the DATABASE_URL as output as it contains a username and
   # password for your database.
   # For example, you can uncomment the lines below to run a database migration command:
   #      - name: Run Migrations
   #        run: npm run db:migrate
   #        env:
   #          # to use pooled connection
-  #          DATABASE_URL: "${{ steps.create_neon_branch.outputs.db_url_with_pooler }}"
+  #          DATABASE_URL: "${{ steps.create_neon_branch.outputs.db_url_pooled }}"
   #          # OR to use unpooled connection
   #          # DATABASE_URL: "${{ steps.create_neon_branch.outputs.db_url }}"
 

.gitignore

@@ -25,3 +25,15 @@ test-results
 .env.*
 !.env.example
 .vercel
+
+# Agent git worktrees (nested checkouts of this repo)
+.claude/worktrees/
+
+# Sleekplan/CSV import test exports dropped in the repo root by manual importer runs.
+# These contain real customer data (names, email addresses) and must never be committed.
+export-*.csv
+
+# Generated SDD review packages: a full `git diff -U10` of a task range, often
+# megabytes, and reproducible from history at any time with `review-package`.
+# The task reports beside them are hand-written and stay tracked.
+.superpowers/sdd/**/review-*.diff

.prettierignore

@@ -4,3 +4,4 @@ node_modules
 dist
 .cache
 server/database/migrations
+server/generated/openapi-routes.ts

.prettierrc.json

@@ -4,5 +4,6 @@
   "trailingComma": "es5",
   "printWidth": 120,
   "tabWidth": 2,
-  "bracketSpacing": true
+  "bracketSpacing": true,
+  "endOfLine": "auto"
 }