30 KiB
30 KiB
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 07-engagement-overview-new | 01 | execute | 1 |
|
true |
|
|
Purpose: Deliver the two read-only data endpoints with requireAuth(), period whitelist
validation, parameterized SQL, manual snake_case → camelCase transform, and exported
TypeScript interfaces (mirrors Phase 4/6 API style). Both endpoints follow CLAUDE.md
rules: no Zod (D-38), no ORM, NextResponse.json envelopes.
Output:
app/api/mobile/engagement/summary/route.ts— GET handler, exportsMobileEngagementSummaryapp/api/mobile/engagement/trend/route.ts— GET handler, exportsSparklinePointandEngagementTrendResponse
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/STATE.md @.planning/ROADMAP.md @.planning/REQUIREMENTS.md @.planning/phases/07-engagement-overview-new/07-CONTEXT.md @.planning/phases/07-engagement-overview-new/07-UI-SPEC.md @CLAUDE.md @app/api/engagement/summary/route.ts @app/api/engagement/users/route.ts @app/api/mobile/analyzer/feed/route.ts @app/api/mobile/tickets/route.ts @migrations/041_create_engagement_tables.sql @migrations/042_add_engagement_calendar_columns.sql @lib/auth-utils.ts @lib/services/msgraph-factory.ts// In existing app/api/engagement/summary/route.ts (lines 42-49) — copy this filter into the new endpoint:
const notAutomatedFilter = `NOT (
es.user_email IS NOT NULL
AND COALESCE(es.emails_received, 0) = 0
AND COALESCE(es.teams_chat_messages, 0) = 0
AND COALESCE(es.teams_meetings_attended, 0) = 0
AND COALESCE(es.teams_calls, 0) = 0
)`;
// Period to interval map (used by both endpoints, matches existing endpoints):
const intervalMap: Record<string, string> = {
D7: '7 days',
D30: '30 days',
D90: '90 days',
};
// requireAuth signature (lib/auth-utils.ts):
export async function requireAuth(): Promise<{ session: Session; error: null } | { session: null; error: NextResponse }>;
// isMsgraphConfigured (lib/services/msgraph-factory.ts):
export function isMsgraphConfigured(): boolean;
// postgresClient (lib/services/postgres-client.ts):
postgresClient.query(sql: string, params?: unknown[]): Promise<{ rows: any[] }>;
// Interfaces this plan MUST export (consumed by 07-03 page):
export interface MobileEngagementSummary {
configured: boolean;
activeUsers: number;
totalGraphHours: number; // 1 decimal, derived from audio + meeting seconds
totalAutotaskHours: number; // 1 decimal, sum of time_entries.hours_worked
hoursPerActiveUser: number; // totalAutotaskHours / activeUsers (0 if activeUsers === 0)
}
export interface SparklinePoint {
date: string; // "YYYY-MM-DD"
hours: number; // total Autotask hours for that day across all matched users (0 if no entries)
}
export interface EngagementTrendResponse {
points: SparklinePoint[]; // D7→7, D30→30, D90→90 points
}
**Imports (top of file):**
```ts
import { NextRequest, NextResponse } from 'next/server';
import { requireAuth } from '@/lib/auth-utils';
import postgresClient from '@/lib/services/postgres-client';
import { isMsgraphConfigured } from '@/lib/services/msgraph-factory';
```
**Exported interface (must match UI-SPEC API Shape Contract verbatim):**
```ts
export interface MobileEngagementSummary {
configured: boolean;
activeUsers: number;
totalGraphHours: number;
totalAutotaskHours: number;
hoursPerActiveUser: number;
}
```
**Period whitelist (D-07, D-32, security threat T-07-04):**
```ts
const ALLOWED_PERIODS = ['D7', 'D30', 'D90'] as const;
type AllowedPeriod = typeof ALLOWED_PERIODS[number];
function parsePeriod(raw: string | null): AllowedPeriod | null {
if (!raw) return 'D30'; // default per D-04
return (ALLOWED_PERIODS as readonly string[]).includes(raw) ? (raw as AllowedPeriod) : null;
}
```
**GET handler shape (per D-09, D-32, D-33):**
```ts
export async function GET(request: NextRequest): Promise<NextResponse> {
const { error: authError } = await requireAuth();
if (authError) return authError;
const { searchParams } = request.nextUrl;
const period = parsePeriod(searchParams.get('period'));
if (period === null) {
return NextResponse.json(
{ error: 'Invalid period', message: "period must be one of 'D7', 'D30', 'D90'" },
{ status: 400 },
);
}
try {
// 1. Latest snapshot date for this period (mirrors existing /api/engagement/summary)
const latestResult = await postgresClient.query(
`SELECT MAX(period_end) as latest_date FROM engagement_snapshots WHERE period_type = $1`,
[period],
);
const latestDate = latestResult.rows[0]?.latest_date;
if (!latestDate) {
return NextResponse.json({
configured: isMsgraphConfigured(),
activeUsers: 0,
totalGraphHours: 0,
totalAutotaskHours: 0,
hoursPerActiveUser: 0,
} satisfies MobileEngagementSummary);
}
const intervalMap: Record<AllowedPeriod, string> = { D7: '7 days', D30: '30 days', D90: '90 days' };
const interval = intervalMap[period];
// notAutomatedFilter — copy verbatim from app/api/engagement/summary/route.ts:42-49
const notAutomatedFilter = `NOT (
es.user_email IS NOT NULL
AND COALESCE(es.emails_received, 0) = 0
AND COALESCE(es.teams_chat_messages, 0) = 0
AND COALESCE(es.teams_meetings_attended, 0) = 0
AND COALESCE(es.teams_calls, 0) = 0
)`;
// 2. activeUsers — match the existing summary endpoint's "active this period" query
// (count of distinct users with teams meetings/messages/emails activity)
const activeResult = await postgresClient.query(
`SELECT COUNT(DISTINCT es.user_email) as count
FROM engagement_snapshots es
JOIN graph_users gu ON LOWER(gu.email) = LOWER(es.user_email)
JOIN (
SELECT DISTINCT ON (LOWER(email)) id, email
FROM resources
WHERE (is_deleted = false OR is_deleted IS NULL) AND email IS NOT NULL
ORDER BY LOWER(email), id
) r ON LOWER(r.email) = LOWER(gu.email)
WHERE es.period_type = $1 AND es.period_end = $2
AND (es.teams_meetings_attended > 0 OR es.teams_chat_messages > 0 OR es.emails_sent > 0)
AND gu.account_enabled = true
AND LOWER(gu.email) LIKE '%@wulfconsulting.%'
AND LOWER(gu.email) NOT LIKE '%#ext#%'
AND ${notAutomatedFilter}`,
[period, latestDate],
);
const activeUsers = parseInt(activeResult.rows[0]?.count ?? '0', 10);
// 3. totalGraphHours — sum(audio_duration_seconds + meeting_duration_seconds) / 3600 for matched users
const graphHoursResult = await postgresClient.query(
`SELECT COALESCE(SUM(COALESCE(es.audio_duration_seconds, 0) + COALESCE(es.meeting_duration_seconds, 0)), 0) AS total_seconds
FROM engagement_snapshots es
JOIN graph_users gu ON LOWER(gu.email) = LOWER(es.user_email)
JOIN (
SELECT DISTINCT ON (LOWER(email)) id, email
FROM resources
WHERE (is_deleted = false OR is_deleted IS NULL) AND email IS NOT NULL
ORDER BY LOWER(email), id
) r ON LOWER(r.email) = LOWER(gu.email)
WHERE es.period_type = $1 AND es.period_end = $2
AND gu.account_enabled = true
AND LOWER(gu.email) LIKE '%@wulfconsulting.%'
AND LOWER(gu.email) NOT LIKE '%#ext#%'
AND ${notAutomatedFilter}`,
[period, latestDate],
);
const totalGraphSeconds = parseFloat(graphHoursResult.rows[0]?.total_seconds ?? '0');
const totalGraphHours = Math.round((totalGraphSeconds / 3600) * 10) / 10;
// 4. totalAutotaskHours — SUM(time_entries.hours_worked) for matched human resources in interval
// NOTE: ${interval} is interpolated NOT parameterized. Safe because period is whitelisted above.
const atHoursResult = await postgresClient.query(
`SELECT COALESCE(SUM(te.hours_worked), 0) AS total_hours
FROM time_entries te
JOIN resources r ON r.id = te.resource_id AND (r.is_deleted = false OR r.is_deleted IS NULL)
JOIN graph_users gu ON LOWER(gu.email) = LOWER(r.email)
WHERE te.entry_date >= NOW() - INTERVAL '${interval}'
AND (te.is_deleted = false OR te.is_deleted IS NULL)
AND gu.account_enabled = true
AND LOWER(gu.email) LIKE '%@wulfconsulting.%'
AND LOWER(gu.email) NOT LIKE '%#ext#%'`,
);
const totalAutotaskHours = Math.round(parseFloat(atHoursResult.rows[0]?.total_hours ?? '0') * 10) / 10;
// 5. hoursPerActiveUser — totalAutotaskHours / activeUsers (0 if activeUsers === 0; UI renders "—")
const hoursPerActiveUser = activeUsers === 0
? 0
: Math.round((totalAutotaskHours / activeUsers) * 10) / 10;
return NextResponse.json({
configured: isMsgraphConfigured(),
activeUsers,
totalGraphHours,
totalAutotaskHours,
hoursPerActiveUser,
} satisfies MobileEngagementSummary);
} catch (error) {
console.error('GET /api/mobile/engagement/summary failed:', error);
return NextResponse.json(
{ error: 'Failed to fetch engagement summary', message: error instanceof Error ? error.message : 'unknown' },
{ status: 500 },
);
}
}
```
**Per D-09:** This endpoint exists because the existing `/api/engagement/summary` returns averages (avgHoursWorked, avgTeamsMeetings, etc.), not the four totals ENG-03 specifies. We reuse the SAME SQL filters/joins (notAutomatedFilter, account_enabled + email scoping, resources DISTINCT ON dedupe) for consistency.
**Per D-32:** `requireAuth()` gates every request. **Do not call any DB code before this gate.**
**Per D-33:** Document inherited risk for the existing `/api/engagement/users` endpoint (which lacks `requireAuth()`) in the threat model — but DO NOT modify the desktop endpoint (out of scope per D-34 and PROJECT.md "Restyling or replacing the desktop pages…").
**Per D-36:** Read-only consumption — no edits to `lib/services/msgraph-*` or `lib/services/engagement-sync-service.ts`.
**Per D-38 / CLAUDE.md:** No Zod. The whitelist function above is sufficient input validation.
**Imports:**
```ts
import { NextRequest, NextResponse } from 'next/server';
import { requireAuth } from '@/lib/auth-utils';
import postgresClient from '@/lib/services/postgres-client';
```
**Exported interfaces (must match UI-SPEC API Shape Contract):**
```ts
export interface SparklinePoint {
date: string; // ISO date string "YYYY-MM-DD"
hours: number; // total Autotask hours for that day (0 if no entries)
}
export interface EngagementTrendResponse {
points: SparklinePoint[]; // D7 → 7, D30 → 30, D90 → 90 points
}
```
**Period whitelist (same as Task 1, copy):**
```ts
const ALLOWED_PERIODS = ['D7', 'D30', 'D90'] as const;
type AllowedPeriod = typeof ALLOWED_PERIODS[number];
const PERIOD_DAYS: Record<AllowedPeriod, number> = { D7: 7, D30: 30, D90: 90 };
function parsePeriod(raw: string | null): AllowedPeriod | null {
if (!raw) return 'D30';
return (ALLOWED_PERIODS as readonly string[]).includes(raw) ? (raw as AllowedPeriod) : null;
}
```
**GET handler — daily aggregate query:**
The query aggregates `time_entries.hours_worked` per `entry_date` for human resources matching `graph_users` in the period. Unlike Task 1's totals, this produces one row per day so the sparkline can render a continuous line.
```ts
export async function GET(request: NextRequest): Promise<NextResponse> {
const { error: authError } = await requireAuth();
if (authError) return authError;
const { searchParams } = request.nextUrl;
const period = parsePeriod(searchParams.get('period'));
if (period === null) {
return NextResponse.json(
{ error: 'Invalid period', message: "period must be one of 'D7', 'D30', 'D90'" },
{ status: 400 },
);
}
const days = PERIOD_DAYS[period];
// T-07-03 mitigation: bounded by whitelisted period (max 90 days). No user-supplied row cap.
try {
// generate_series produces one row per day so days with zero hours are still represented (D-15: continuous line, no gaps).
// ${days} is interpolated NOT parameterized — safe because period is whitelisted to 7/30/90.
const sql = `
WITH day_series AS (
SELECT generate_series(
(CURRENT_DATE - INTERVAL '${days - 1} days')::date,
CURRENT_DATE,
INTERVAL '1 day'
)::date AS day
),
daily_hours AS (
SELECT te.entry_date::date AS day, COALESCE(SUM(te.hours_worked), 0) AS hours
FROM time_entries te
JOIN resources r ON r.id = te.resource_id AND (r.is_deleted = false OR r.is_deleted IS NULL)
JOIN graph_users gu ON LOWER(gu.email) = LOWER(r.email)
WHERE te.entry_date >= CURRENT_DATE - INTERVAL '${days - 1} days'
AND te.entry_date <= CURRENT_DATE
AND (te.is_deleted = false OR te.is_deleted IS NULL)
AND gu.account_enabled = true
AND LOWER(gu.email) LIKE '%@wulfconsulting.%'
AND LOWER(gu.email) NOT LIKE '%#ext#%'
GROUP BY te.entry_date::date
)
SELECT to_char(ds.day, 'YYYY-MM-DD') AS date,
COALESCE(dh.hours, 0)::numeric AS hours
FROM day_series ds
LEFT JOIN daily_hours dh ON dh.day = ds.day
ORDER BY ds.day ASC
`;
const result = await postgresClient.query(sql);
const points: SparklinePoint[] = result.rows.map(row => ({
date: String(row.date),
hours: Math.round(parseFloat(row.hours ?? '0') * 10) / 10,
}));
return NextResponse.json({ points } satisfies EngagementTrendResponse);
} catch (error) {
console.error('GET /api/mobile/engagement/trend failed:', error);
return NextResponse.json(
{ error: 'Failed to fetch engagement trend', message: error instanceof Error ? error.message : 'unknown' },
{ status: 500 },
);
}
}
```
**Per D-12 / D-15:** Continuous series — `generate_series` ensures every day in the period has a row even when zero hours were logged (no gaps). The UI sparkline draws zero-hour days down to baseline, never breaks the line.
**Per D-32:** `requireAuth()` is the first call — DB queries only run after auth.
**Per D-38:** No Zod. Whitelist sufficient.
**Per D-34, D-36:** No edits to existing engagement endpoints, services, or migrations.
**Per security threat T-07-03 (rate-limiting/DoS):** Period whitelist caps the date range to ≤90 days; the query has bounded results (one row per day, max 90). No user-supplied row-count parameter.
<threat_model>
Trust Boundaries
| Boundary | Description |
|---|---|
| Browser → /api/mobile/engagement/* | Authenticated mobile clients send GET requests with cookie-based session; period query param is untrusted input |
| Mobile API → Postgres | Endpoints query engagement_snapshots, graph_users, resources, time_entries; SQL parameters supplied by handler (period whitelisted) |
| Mobile API → MSGraph factory | Read-only isMsgraphConfigured() boolean check; no credential exposure |
STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|---|---|---|---|---|
| T-07-01 | Spoofing/AuthN | summary + trend GET handlers | mitigate | Both handlers call requireAuth() from lib/auth-utils.ts as the FIRST statement; if authError is non-null, return immediately. Acceptance criteria check enforces ordering via awk grep. |
| T-07-02 | Tampering / Injection | period query parameter | mitigate | Whitelist ['D7','D30','D90'] via parsePeriod(). Invalid values return 400 BEFORE any SQL executes. The whitelisted period is then used both as a bound parameter ($1) and to look up a static INTERVAL '7 days' / '30 days' / '90 days' constant — interpolation is on a fixed map value, not user input. |
| T-07-03 | DoS / Resource exhaustion | trend endpoint daily aggregation | mitigate | Whitelist caps the date range to max 90 days. generate_series produces at most 90 rows. No user-supplied row-count or page-size parameter. SQL aggregation runs against indexed columns (entry_date, resource_id per existing engagement endpoints — no new index required). |
| T-07-04 | Information Disclosure | summary/trend response payloads | mitigate | Both endpoints return ONLY scalars (totals, hours-per-day) — no per-user PII (no display_name, no email, no jobTitle). Sensitive metadata (teams_chat_messages, emails_sent, etc.) is summed, never enumerated. |
| T-07-05 | Information Disclosure (inherited) | existing /api/engagement/users (NOT modified by this plan) |
accept | Existing desktop endpoint lacks requireAuth() (CONTEXT.md D-33). Reuse from Plan 03 does not increase exposure since middleware.ts blocks unauth access to /api/* not in the public list (verify on first run). Out of scope per D-34 + PROJECT.md ("Restyling or replacing the desktop pages…"). Document follow-up; recommend a future security phase. Mirrors Phase 6 IDOR T-06P03-02 disposition pattern. |
| T-07-06 | Repudiation | Both new endpoints | accept | Read-only GET endpoints surfacing aggregate metrics. No state mutation, no audit trail required. Standard console.error logging on exception paths. |
| </threat_model> |
<success_criteria>
- Both files written, both export the documented interfaces
npx tsc --noEmit --prettyexits 0- Period whitelist enforced (D7/D30/D90 only) on both endpoints
requireAuth()is the first statement in each handler- No Zod, no ORM, no edits outside the two new files
- Plan 03 can
import type { MobileEngagementSummary } from '@/app/api/mobile/engagement/summary/route'andimport type { SparklinePoint, EngagementTrendResponse } from '@/app/api/mobile/engagement/trend/route'without errors </success_criteria>