diff --git a/infrastructure/analytics-api/README.md b/infrastructure/analytics-api/README.md index a13469bea..19aecdafb 100644 --- a/infrastructure/analytics-api/README.md +++ b/infrastructure/analytics-api/README.md @@ -23,7 +23,8 @@ strict dates, bounded UTM/surface tokens, and an exact query-free path. SQL is s API named parameters; callers cannot provide SQL, object names, sort clauses, or result limits. -Reports are limited to 366 inclusive days and 2,000 decoded rows. Query waits +Reports are limited to 366 inclusive days and 2,000 decoded rows, with an additional +allowance of four rows per selected day for SpaceTech’s daily source metrics. Query waits leave time for a sanitized response. A failed or aborted statement is retried once within the same deadline. Clients can opt into resumable requests with `async=true`. If Redshift Serverless needs longer than one HTTP request, the API @@ -171,7 +172,9 @@ parameter remains accepted for API compatibility, but content no longer splits campaign rows or appears in the UI. Distinct visitors are recomputed across all content values, rather than summing distinct counts. `filterOptions` contains available source/medium/campaign values for the date range independently of -selected UTM filters. The SpaceTech tab defaults to 90 days. +selected UTM filters. The campaign starts on November 5, 2026 at 00:00 UTC. +Overlapping requests use that date as their earliest start. Requests ending +before launch return HTTP 400. The SpaceTech tab defaults to up to 90 days. The API retains its JWT/analytics-role gate, parameterized queries, 60-second cache and resumable-query protocol. `dataThrough` is now the UTC timestamp of @@ -280,7 +283,7 @@ is not a promise that the visitor is still online. Simultaneous tabs cannot be unambiguously distinguished without a future per-form-instance tracking ID. Activity follows warehouse ingestion, while submitted lead details remain -immediate. The existing 2,000-row response limit still fails explicitly rather +immediate. The response row limit still fails explicitly rather than silently truncating activity. Historical FAQ opens and form-section exposure cannot be reconstructed without the corresponding website instrumentation. @@ -290,8 +293,8 @@ procedure in place until no deployment uses them. No data deletion is needed. ### SpaceTech source dashboard (PM-6775) -The same endpoint now adds `personas` (full-period totals) and `personaSeries` -(weekly metrics), both for Topcoder, George, Anita and Tony. The persona is the +The endpoint returns `personas` (full-period totals), `dailyPersonaSeries` (daily metrics), +and `personaSeries` (weekly metrics) for Topcoder, George, Anita and Tony. The persona is the fourth underscore-delimited token in `customer_spacetech_[period]_[persona]_…`, matched case-insensitively from **utm_campaign only**. Source, medium and content never assign a persona. Unknown names and unattributed traffic remain in the @@ -303,9 +306,8 @@ multiple sources. Rates use aggregate numerators/denominators, never sums or averages of daily/campaign rates. Submissions/visitors can exceed 100%; zero denominators yield zero. Weekly buckets start Monday at 00:00 UTC, and first/last weeks include only events inside the requested inclusive dates. Quiet weeks and -missing sources are zero-filled. At the maximum 366-day range, the new SQL adds -at most 220 aggregate rows (four totals plus four × 54 weeks), retaining the -existing 2,000-row result limit and bounded polling protocol. +missing sources are zero-filled. Daily buckets follow the same attribution and date filters. The SpaceTech query +allows four extra rows per selected day, up to 1,464 extra rows for a 366-day range. Deploy the updated `handler.py` to the existing development analytics Lambda using a versioned S3 zip and the stack's `CodeKey` parameter. No warehouse DDL, diff --git a/infrastructure/analytics-api/src/handler.py b/infrastructure/analytics-api/src/handler.py index e297272fb..9293ee01d 100644 --- a/infrastructure/analytics-api/src/handler.py +++ b/infrastructure/analytics-api/src/handler.py @@ -20,6 +20,7 @@ MAX_DATE_RANGE_DAYS = 366 +SPACETECH_CAMPAIGN_START = "2026-11-05" MAX_RESULT_ROWS = 2_000 MAX_QUERY_ATTEMPTS = 2 REPORT_CACHE_SECONDS = 60 @@ -377,7 +378,7 @@ """ -SPACETECH_SQL = """ +SPACETECH_SQL = f""" WITH form_events AS ( SELECT * FROM topcoder_web.spacetech_form_events_v1 WHERE event_timestamp >= CAST(:from_date AS timestamp) @@ -422,11 +423,13 @@ AND LOWER(SPLIT_PART(campaign, '_', 2)) = 'spacetech' AND LOWER(SPLIT_PART(campaign, '_', 4)) IN ('topcoder', 'george', 'anita', 'tony') THEN LOWER(SPLIT_PART(campaign, '_', 4)) END AS persona, + event_timestamp::date AS event_day, DATE_TRUNC('week', event_timestamp)::date AS week_start FROM events ) SELECT 'summary'::varchar AS row_type, NULL::varchar AS dimension_1, NULL::varchar AS dimension_2, NULL::varchar AS dimension_3, - (SELECT MAX(event_timestamp)::varchar FROM topcoder_web.spacetech_events_mv_v2) AS dimension_4, + (SELECT MAX(event_timestamp)::varchar FROM topcoder_web.spacetech_events_mv_v2 + WHERE event_timestamp >= TIMESTAMP '{SPACETECH_CAMPAIGN_START}') AS dimension_4, COUNT(CASE WHEN event_name = '_page_view' THEN 1 END)::bigint AS page_views, COUNT(DISTINCT CASE WHEN event_name = '_page_view' THEN analytics_user_id END)::bigint AS visitors, @@ -464,7 +467,10 @@ FROM events GROUP BY 2, 3, 4 UNION ALL -SELECT 'persona'::varchar AS row_type, persona AS dimension_1, NULL::varchar AS dimension_2, +SELECT CASE WHEN GROUPING(event_day) = 0 THEN 'persona_daily' + WHEN GROUPING(week_start) = 0 THEN 'persona_weekly' + ELSE 'persona' END::varchar AS row_type, + persona AS dimension_1, COALESCE(event_day, week_start)::varchar AS dimension_2, NULL::varchar AS dimension_3, NULL::varchar AS dimension_4, COUNT(CASE WHEN event_name = '_page_view' THEN 1 END)::bigint AS page_views, COUNT(DISTINCT CASE WHEN event_name = '_page_view' THEN analytics_user_id END)::bigint AS visitors, @@ -475,20 +481,7 @@ COUNT(*)::bigint AS events, COUNT(DISTINCT analytics_user_id)::bigint AS users FROM persona_events WHERE persona IS NOT NULL -GROUP BY persona -UNION ALL -SELECT 'persona_weekly'::varchar AS row_type, persona AS dimension_1, week_start::varchar AS dimension_2, - NULL::varchar AS dimension_3, NULL::varchar AS dimension_4, - COUNT(CASE WHEN event_name = '_page_view' THEN 1 END)::bigint AS page_views, - COUNT(DISTINCT CASE WHEN event_name = '_page_view' THEN analytics_user_id END)::bigint AS visitors, - COUNT(CASE WHEN event_name = 'form_started' THEN 1 END)::bigint AS starts, - COUNT(CASE WHEN event_name = 'form_completed' THEN 1 END)::bigint AS submissions, - COUNT(DISTINCT CASE WHEN event_name = 'form_section_reached' THEN analytics_user_id END)::bigint AS reached, - COALESCE(SUM(CASE WHEN event_name = '_user_engagement' THEN user_engagement_time_msec ELSE 0 END), 0)::bigint AS engagement_ms, - COUNT(*)::bigint AS events, - COUNT(DISTINCT analytics_user_id)::bigint AS users -FROM persona_events WHERE persona IS NOT NULL -GROUP BY persona, week_start +GROUP BY GROUPING SETS ((persona), (persona, week_start), (persona, event_day)) UNION ALL SELECT 'country'::varchar AS row_type, country AS dimension_1, NULL::varchar AS dimension_2, NULL::varchar AS dimension_3, NULL::varchar AS dimension_4, @@ -941,6 +934,9 @@ def handler(event: dict[str, Any], context: Any) -> dict[str, Any]: key: _safe_filter(query.get(key), key) for key in ("source", "medium", "campaign", "content") }} + if filters["to"] < SPACETECH_CAMPAIGN_START: + raise ValueError(f"SpaceTech reporting starts on {SPACETECH_CAMPAIGN_START}") + filters["from"] = max(filters["from"], SPACETECH_CAMPAIGN_START) report = _cached_report( f"spacetech:{json.dumps(filters, sort_keys=True)}", REPORT_CACHE_SECONDS, @@ -1662,6 +1658,7 @@ def _execute_query( context: Any, query_token: str | None = None, maximum_wait_seconds: float = 24.0, + max_result_rows: int = MAX_RESULT_ROWS, ) -> list[dict[str, Any]]: """Execute a fixed parameterized query with resumable timeout handling. @@ -1670,6 +1667,8 @@ def _execute_query( parameters: Validated Data API named parameters. context: Lambda context or null for the cached filter loader. query_token: Optional server-issued token that resumes a pending statement. + maximum_wait_seconds: Upper bound on the query wait. + max_result_rows: Upper bound on decoded rows for this report. Returns: Query rows keyed by Redshift column name. @@ -1706,7 +1705,7 @@ def _execute_query( if status["Status"] == "FINISHED": if status.get("HasResultSet") is False: return [] - return _statement_rows(statement_id) + return _statement_rows(statement_id, max_result_rows) if status["Status"] in {"FAILED", "ABORTED"}: if attempt + 1 < MAX_QUERY_ATTEMPTS: break @@ -1798,11 +1797,12 @@ def _query_wait_seconds(context: Any, maximum: float = 24.0) -> float: return maximum -def _statement_rows(statement_id: str) -> list[dict[str, Any]]: +def _statement_rows(statement_id: str, max_result_rows: int) -> list[dict[str, Any]]: """Page through one Data API result without exceeding the response contract. Args: statement_id: Completed Data API statement identifier. + max_result_rows: Upper bound across all pages. Returns: Decoded query rows. @@ -1821,7 +1821,7 @@ def _statement_rows(statement_id: str) -> list[dict[str, Any]]: columns = [column["name"] for column in page.get("ColumnMetadata", [])] rows.extend({name: _field_value(field) for name, field in zip(columns, record)} for record in page.get("Records", [])) - if len(rows) > MAX_RESULT_ROWS: + if len(rows) > max_result_rows: raise QueryFailure("Analytics query exceeded the result row bound") next_token = page.get("NextToken") if not next_token: @@ -2077,7 +2077,11 @@ def _now_iso() -> str: def _spacetech_report(filters: dict[str, str], context: Any, query_token: str | None = None) -> dict[str, Any]: """Return aggregate SpaceTech traffic and form conversions; never expose lead answers or visitor IDs.""" - rows = _execute_query(SPACETECH_SQL, _sql_parameters(filters), context, query_token) + start, end = date.fromisoformat(filters["from"]), date.fromisoformat(filters["to"]) + personas = ("topcoder", "george", "anita", "tony") + days = (end - start).days + 1 + rows = _execute_query(SPACETECH_SQL, _sql_parameters(filters), context, query_token, + max_result_rows=MAX_RESULT_ROWS + len(personas) * days) def metrics(row: dict[str, Any]) -> dict[str, Any]: """Use visitors as the submission-rate denominator and page views for engaged time.""" @@ -2101,14 +2105,18 @@ def groups(kind: str, dimensions: list[str]) -> list[dict[str, Any]]: daily = {row["date"]: row for row in groups("daily", ["date"])} # Include quiet campaign days so a two-month chart does not collapse gaps. - start, end = date.fromisoformat(filters["from"]), date.fromisoformat(filters["to"]) + persona_daily = {(row["dimension_2"], row["dimension_1"]): metrics(row) + for row in rows if row["row_type"] == "persona_daily"} series = [] - for offset in range((end - start).days + 1): + daily_persona_series = [] + for offset in range(days): day = (start + timedelta(days=offset)).isoformat() series.append(daily.get(day, {"date": day, **metrics({})})) + daily_persona_series.append({"date": day, **{ + persona: persona_daily.get((day, persona), metrics({})) for persona in personas + }}) # Compute distinct visitors over each whole persona/period in SQL; never # sum daily or campaign-level uniques or average already-calculated rates. - personas = ("topcoder", "george", "anita", "tony") persona_totals = {row["dimension_1"]: metrics(row) for row in rows if row.get("row_type") == "persona"} persona_weekly = {(row["dimension_1"], row["dimension_2"]): metrics(row) @@ -2137,6 +2145,7 @@ def groups(kind: str, dimensions: list[str]) -> list[dict[str, Any]]: "personas": [{"persona": persona, **persona_totals.get(persona, metrics({}))} for persona in personas], "personaSeries": persona_series, + "dailyPersonaSeries": daily_persona_series, "campaigns": groups("campaign", ["source", "medium", "campaign"]), "filterOptions": { key: sorted({row["dimension_1"] for row in rows diff --git a/infrastructure/analytics-api/tests/test_handler.py b/infrastructure/analytics-api/tests/test_handler.py index 3f40e0402..e4dd4a71c 100644 --- a/infrastructure/analytics-api/tests/test_handler.py +++ b/infrastructure/analytics-api/tests/test_handler.py @@ -8,6 +8,7 @@ import sys import types import unittest +from datetime import datetime, timezone from pathlib import Path from unittest.mock import Mock, patch @@ -119,7 +120,7 @@ def test_spacetech_report_attribution_rates_and_quiet_days(self) -> None: rows = [ {"row_type": "summary", "page_views": 20, "visitors": 10, "starts": 5, "submissions": 2, "reached": 7, "engagement_ms": 100000}, - {"row_type": "daily", "dimension_1": "2026-09-01", "visitors": 10, "submissions": 2}, + {"row_type": "daily", "dimension_1": "2026-11-05", "visitors": 10, "submissions": 2}, {"row_type": "campaign", "dimension_1": "linkedin", "dimension_2": "social", "dimension_3": "customer_spacetech_nov26_george", "dimension_4": "post_1", "visitors": 10, "submissions": 2}, @@ -128,7 +129,7 @@ def test_spacetech_report_attribution_rates_and_quiet_days(self) -> None: {"row_type": "option_source", "dimension_1": "email"}, {"row_type": "option_source", "dimension_1": "linkedin"}, ] - query = {"from": "2026-09-01", "to": "2026-09-03", "source": "linkedin", "content": "post_1"} + query = {"from": "2026-11-01", "to": "2026-11-07", "source": "linkedin", "content": "post_1"} with patch.object(self.module, "_execute_query", return_value=rows) as execute: response = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], query), None) self.assertEqual(response["statusCode"], 200) @@ -143,23 +144,26 @@ def test_spacetech_report_attribution_rates_and_quiet_days(self) -> None: self.assertEqual(report["countries"][0]["country"], "") self.assertNotIn("analytics_user_id", response["body"]) params = {item["name"]: item["value"] for item in execute.call_args.args[1]} + self.assertEqual(params["from_date"], "2026-11-05") + self.assertEqual(report["filters"]["from"], "2026-11-05") + self.assertEqual(report["series"][0]["date"], "2026-11-05") self.assertEqual(params["source"], "linkedin") self.assertEqual(params["content"], "post_1") self.assertIn(":content", execute.call_args.args[0]) self.assertNotIn("linkedin", execute.call_args.args[0]) def test_spacetech_form_activity_excludes_identifiers_and_answers(self) -> None: - rows = [{"row_type": kind, "dimension_1": "2026-11-04 12:00:00", + rows = [{"row_type": kind, "dimension_1": "2026-11-05 12:00:00", "dimension_2": "linkedin", "dimension_3": "social", "dimension_4": "campaign", "visitor_id": "private", "session_id": "private", "email": "private"} for kind in ("form_started", "form_incomplete")] with patch.object(self.module, "_execute_query", return_value=rows): response = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], { - "from": "2026-11-04", "to": "2026-11-04", + "from": "2026-11-05", "to": "2026-11-05", }), None) activity = json.loads(response["body"])["formActivity"] self.assertEqual([row["status"] for row in activity], ["Started", "Incomplete"]) - self.assertEqual(activity[0], {"startedAt": "2026-11-04T12:00:00.000Z", "source": "linkedin", + self.assertEqual(activity[0], {"startedAt": "2026-11-05T12:00:00.000Z", "source": "linkedin", "medium": "social", "campaign": "campaign", "status": "Started"}) self.assertNotIn("private", response["body"]) @@ -193,13 +197,16 @@ def test_spacetech_persona_totals_and_weekly_rates(self) -> None: def test_spacetech_empty_personas_cover_maximum_range(self) -> None: """All four sources and up to 54 Monday buckets remain bounded for 366 days.""" - with patch.object(self.module, "_execute_query", return_value=[]): + with patch.object(self.module, "datetime", wraps=datetime) as clock, \ + patch.object(self.module, "_execute_query", return_value=[]): + clock.now.return_value = datetime(2027, 11, 8, tzinfo=timezone.utc) response = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], { - "from": "2025-11-02", "to": "2026-11-02", + "from": "2026-11-08", "to": "2027-11-08", }), None) report = json.loads(response["body"]) self.assertEqual(len(report["personas"]), 4) self.assertEqual(len(report["personaSeries"]), 54) + self.assertEqual(len(report["dailyPersonaSeries"]), 366) for week in report["personaSeries"]: for persona in ("topcoder", "george", "anita", "tony"): self.assertEqual(week[persona]["submissionRate"], 0) @@ -253,8 +260,13 @@ def test_spacetech_empty_report_and_authorization(self) -> None: }), None) self.assertEqual(invalid["statusCode"], 400) execute.assert_not_called() + before_launch = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], { + "to": "2026-11-04", + }), None) + self.assertEqual(before_launch["statusCode"], 400) + execute.assert_not_called() response = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], { - "from": "2026-09-01", "to": "2026-09-01", + "to": "2026-11-05", }), None) report = json.loads(response["body"]) self.assertEqual(report["totals"]["submissionRate"], 0) diff --git a/infrastructure/analytics-api/tests/test_spacetech_sql.py b/infrastructure/analytics-api/tests/test_spacetech_sql.py index e97bd0429..935500f04 100644 --- a/infrastructure/analytics-api/tests/test_spacetech_sql.py +++ b/infrastructure/analytics-api/tests/test_spacetech_sql.py @@ -26,7 +26,7 @@ def setUp(self): event_timestamp TIMESTAMP, visitor_id VARCHAR, session_id VARCHAR, event_name VARCHAR, source VARCHAR, medium VARCHAR, campaign VARCHAR, content VARCHAR )""") - self.params = dict(from_date="2026-11-04", to_date="2026-11-17", + self.params = dict(from_date="2026-11-05", to_date="2026-11-17", source="*", medium="*", campaign="*", content="*") def tearDown(self): @@ -53,15 +53,17 @@ def report(self): return self.handler._spacetech_report(filters, None) def test_distinct_personas_rates_week_boundaries_and_filters(self): + self.event("2026-11-04 23:59:59", "before", source="pre-launch") + self.assertIsNone(self.report()["dataThrough"]) # Same person visits different links/sources/days/weeks: totals must deduplicate. - self.event("2026-11-04", "one") + self.event("2026-11-05", "one") self.event("2026-11-08 23:59:59", "one", source="linkedin", medium="social", content="other") self.event("2026-11-09", "one") self.event("2026-11-09", "two") for event in ("form_started", "form_completed", "form_section_reached"): - self.event("2026-11-04", "one", event=event) + self.event("2026-11-05", "one", event=event) self.event("2026-11-09", "one", event=event) - self.event("2026-11-04", "one", event="_user_engagement", engagement=31000) + self.event("2026-11-05", "one", event="_user_engagement", engagement=31000) # Other personas, uppercase naming, suffixes, and unknown campaigns. self.event("2026-11-05", "one", persona="ANITA") self.event("2026-11-05", "three", persona="tony") @@ -70,10 +72,10 @@ def test_distinct_personas_rates_week_boundaries_and_filters(self): self.event("2026-11-05", "six", campaign="", source="topcoder", medium="anita") self.event("2026-11-05", "seven", campaign="other_spacetech_nov26_george") self.event("2026-11-05", "eight", campaign="customer_spacetech_nov26_unknown_george") - # Both edges are excluded despite sharing a week with included dates. - self.event("2026-11-03 23:59:59", "outside") + # The day after the range is excluded despite sharing the final week. self.event("2026-11-18", "outside") report = self.report() + self.assertNotIn("pre-launch", report["filterOptions"]["source"]) george = report["personas"][1] self.assertEqual((george["pageViews"], george["visitors"], george["starts"], george["submissions"], george["reached"], george["submissionRate"], george["averageEngagementSeconds"]), @@ -81,10 +83,17 @@ def test_distinct_personas_rates_week_boundaries_and_filters(self): self.assertEqual([row["visitors"] for row in report["personas"]], [1, 2, 1, 1]) self.assertEqual([row["george"]["visitors"] for row in report["personaSeries"]], [1, 2, 0]) self.assertEqual([row["george"]["submissionRate"] for row in report["personaSeries"]], [100, 50, 0]) + days = report["dailyPersonaSeries"] + self.assertEqual([row["date"] for row in days], [row["date"] for row in report["series"]]) + self.assertEqual([row["george"]["pageViews"] for row in days[:5]], [1, 0, 0, 1, 2]) + self.assertEqual(days[0]["george"]["averageEngagementSeconds"], 31) + self.assertEqual(days[4]["george"]["submissionRate"], 50) + self.assertEqual(days[0]["anita"]["visitors"], 1) self.assertEqual(report["totals"]["pageViews"], 11) self.params.update(source="linkedin", medium="social", content="other") report = self.report() self.assertEqual(report["personas"][1]["pageViews"], 1) + self.assertEqual([row["george"]["visitors"] for row in report["dailyPersonaSeries"][:5]], [0, 0, 0, 1, 0]) self.assertEqual(report["personas"][1]["submissions"], 0) self.assertEqual(report["personas"][2]["visitors"], 0) self.assertIn("email", report["filterOptions"]["source"]) @@ -95,8 +104,8 @@ def test_empty_and_zero_denominators(self): report = self.report() self.assertEqual(len(report["personas"]), 4) self.assertEqual(len(report["personaSeries"]), 3) - self.event("2026-11-04", "one", event="form_completed") - self.event("2026-11-04", "one", event="_user_engagement", engagement=10000) + self.event("2026-11-05", "one", event="form_completed") + self.event("2026-11-05", "one", event="_user_engagement", engagement=10000) george = self.report()["personas"][1] self.assertEqual(george["submissions"], 1) self.assertEqual(george["submissionRate"], 0) @@ -107,21 +116,21 @@ def form_event(self, time, visitor, event, session="session", source="email", ca [time, visitor, session, event, source, "social", campaign, "post"]) def test_form_status_lifecycle_repeat_attempts_and_private_fields(self): - self.form_event("2026-11-04 10:00:00", "started", "form_started") - self.form_event("2026-11-04 11:00:00", "incomplete", "form_started") - self.form_event("2026-11-04 11:01:00", "incomplete", "form_abandoned") + self.form_event("2026-11-05 10:00:00", "started", "form_started") + self.form_event("2026-11-05 11:00:00", "incomplete", "form_started") + self.form_event("2026-11-05 11:01:00", "incomplete", "form_abandoned") # A completion wins even if a pagehide abandonment arrived first. - self.form_event("2026-11-04 12:00:00", "completed", "form_started") - self.form_event("2026-11-04 12:01:00", "completed", "form_abandoned") - self.form_event("2026-11-04 12:02:00", "completed", "form_completed") + self.form_event("2026-11-05 12:00:00", "completed", "form_started") + self.form_event("2026-11-05 12:01:00", "completed", "form_abandoned") + self.form_event("2026-11-05 12:02:00", "completed", "form_completed") # A later successful attempt must not erase a previous incomplete one. - self.form_event("2026-11-04 13:00:00", "repeat", "form_started") - self.form_event("2026-11-04 13:01:00", "repeat", "form_abandoned") - self.form_event("2026-11-04 14:00:00", "repeat", "form_started") - self.form_event("2026-11-04 14:01:00", "repeat", "form_completed") - self.form_event("2026-11-04 15:00:00", "repeat", "form_started") + self.form_event("2026-11-05 13:00:00", "repeat", "form_started") + self.form_event("2026-11-05 13:01:00", "repeat", "form_abandoned") + self.form_event("2026-11-05 14:00:00", "repeat", "form_started") + self.form_event("2026-11-05 14:01:00", "repeat", "form_completed") + self.form_event("2026-11-05 15:00:00", "repeat", "form_started") # Same visitor, different session: must not suppress the unsubmitted attempt. - self.form_event("2026-11-04 15:01:00", "repeat", "form_completed", session="other") + self.form_event("2026-11-05 15:01:00", "repeat", "form_completed", session="other") activity = self.report()["formActivity"] self.assertEqual(len(activity), 4) self.assertEqual(sorted(row["status"] for row in activity), @@ -137,10 +146,10 @@ def test_form_status_date_and_attribution_filters_do_not_hide_terminal_events(se self.form_event("2026-11-18 00:01:00", "complete", "form_completed", source="changed") self.form_event("2026-11-17 23:59:00", "left", "form_started") self.form_event("2026-11-18 00:01:00", "left", "form_abandoned", source="changed") - self.form_event("2026-11-03 23:59:00", "before", "form_started") + self.form_event("2026-11-04 23:59:00", "before", "form_started") self.form_event("2026-11-18 00:00:00", "after", "form_started") - self.form_event("2026-11-04 00:00:00", "other-source", "form_started", source="linkedin") - self.form_event("2026-11-04 00:00:00", "other-campaign", "form_started", campaign="other") + self.form_event("2026-11-05 00:00:00", "other-source", "form_started", source="linkedin") + self.form_event("2026-11-05 00:00:00", "other-campaign", "form_started", campaign="other") self.params.update(source="email", medium="social", campaign="campaign", content="post") self.assertEqual(self.report()["formActivity"], [{ "startedAt": "2026-11-17T23:59:00.000Z", "source": "email", "medium": "social", diff --git a/src/apps/analytics/README.md b/src/apps/analytics/README.md index 1e533e3d1..e683e5e77 100644 --- a/src/apps/analytics/README.md +++ b/src/apps/analytics/README.md @@ -97,7 +97,8 @@ genuine failure, the explicit retry action is shown. SpaceTech Analytics reports `/space-tech` traffic, engagement, FAQ opens, form-section reach and accepted form submissions with source, medium, campaign -dropdown filters. It defaults to 90 days and supports the same 366-day limit. +dropdown filters. Reporting begins on November 5, 2026 (inclusive, UTC). The default covers up to +90 days since launch, and custom ranges support the same 366-day limit. The daily chart compares visitors with form submissions. Lead details appear below the aggregates for users with existing Forms reporting permission, with all-column sorting/filtering and Submitted, Started and Incomplete statuses. Unfinished attempts @@ -158,7 +159,7 @@ checks are documented in ### SpaceTech Dashboard and Details -SpaceTech opens on Dashboard, with a seven-metric selector, weekly line chart +SpaceTech opens on Dashboard, with a seven-metric selector, daily column chart for Topcoder, George, Anita and Tony, and a table of all seven full-period metrics. The shared inclusive UTC date and UTM filters apply to both views. Details keeps the existing totals, daily chart, attribution/CTA/FAQ/country/device tables and @@ -166,8 +167,9 @@ permission-gated leads. Tabs support arrow, Home and End keys. Sources come only from the persona token in `utm_campaign`, following `customer_spacetech_[period]_[persona]_…`; they are independent of `utm_source`. -Unmatched campaigns remain in Details. Weekly buckets start Monday; partial -weeks respect the selected dates. Distinct visitors and rates are computed by +Unmatched campaigns remain in Details. The bars show daily values in UTC. Each +matching line averages the most recent seven daily values in the selected range, +including zero-activity days. Details uses the same display for visitors and submissions. Distinct visitors and rates are computed by the API for each source and period, not combined from displayed campaign rows. The frontend preserves decimals for percentage and engagement metrics. An older API without the new fields shows an unavailable message instead of false zeros. diff --git a/src/apps/analytics/src/lib/components/TimeSeriesChart/TimeSeriesChart.spec.tsx b/src/apps/analytics/src/lib/components/TimeSeriesChart/TimeSeriesChart.spec.tsx new file mode 100644 index 000000000..6a011357c --- /dev/null +++ b/src/apps/analytics/src/lib/components/TimeSeriesChart/TimeSeriesChart.spec.tsx @@ -0,0 +1,43 @@ +/* eslint-disable import/no-extraneous-dependencies, ordered-imports/ordered-imports, unicorn/no-null */ +import '@testing-library/jest-dom' +import { render, screen, within } from '@testing-library/react' +import HighchartsReact from 'highcharts-react-official' + +import { TimeSeriesChart } from './TimeSeriesChart' + +jest.mock('highcharts-react-official', () => jest.fn(() => null)) + +const series = [{ color: '#137d60', key: 'visitors', label: 'Visitors' }] +const points = [14, 0, 0, 0, 0, 0, 0, 1].map((visitors, index) => ({ + date: new Date(Date.UTC(2026, 10, 5 + index)) + .toISOString() + .slice(0, 10), + visitors, +})) + +describe('TimeSeriesChart', () => { + it('overlays daily columns with a linked seven-day trend and exposes both values in the table', () => { + render() + const [columns, trend] = (HighchartsReact as unknown as jest.Mock).mock.calls[0][0].options.series + expect(columns) + .toMatchObject({ data: [14, 0, 0, 0, 0, 0, 0, 1], type: 'column' }) + expect(trend) + .toMatchObject({ data: [14, 7, 4.67, 3.5, 2.8, 2.33, 2, 0.14], linkedTo: columns.id, type: 'line' }) + const table = within(screen.getByRole('table', { name: 'Daily visitors' })) + expect(table.getByRole('columnheader', { name: 'Visitors (7-day average)' })) + .toBeInTheDocument() + expect(table.getAllByRole('row')[8]) + .toHaveTextContent('0.14') + }) + + it('keeps the existing empty state when all daily values are zero', () => { + render() + expect(screen.getByRole('status')) + .toHaveTextContent('No activity is available') + }) +}) diff --git a/src/apps/analytics/src/lib/components/TimeSeriesChart/TimeSeriesChart.tsx b/src/apps/analytics/src/lib/components/TimeSeriesChart/TimeSeriesChart.tsx index 402290fd9..d186815c1 100644 --- a/src/apps/analytics/src/lib/components/TimeSeriesChart/TimeSeriesChart.tsx +++ b/src/apps/analytics/src/lib/components/TimeSeriesChart/TimeSeriesChart.tsx @@ -1,4 +1,4 @@ -/** Reusable accessible line chart for daily analytics series. */ +/** Accessible time series chart for analytics reports. */ /* eslint-disable ordered-imports/ordered-imports */ import Highcharts from 'highcharts' import HighchartsReact from 'highcharts-react-official' @@ -18,7 +18,7 @@ interface TimeSeriesChartProps { ariaLabel: string points: object[] series: TimeSeriesDefinition[] - variant?: 'area' | 'line' + variant?: 'area' | 'line' | 'column-trend' valueDecimals?: number valueSuffix?: string xAxisTitle?: string @@ -38,22 +38,65 @@ function pointValue(point: object, key: string): number { return typeof value === 'number' && Number.isFinite(value) ? value : 0 } +/** Average up to seven consecutive UTC days from the selected range, including quiet days. */ +function sevenDayAverage(values: number[]): number[] { + return values.map((_, index) => { + const window = values.slice(Math.max(0, index - 6), index + 1) + const average = window.reduce((total, value) => total + value, 0) / window.length + return Number(average.toFixed(2)) + }) +} + /** - * Renders a multi-series daily line chart and an equivalent screen-reader table. + * Renders daily series and an equivalent screen-reader table. * - * @param props accessible label, normalized points, series definitions, and optional line/area variant. + * @param props accessible label, normalized points, series definitions, and chart variant. * @returns chart, accessible table, or explicit empty state. * @throws Does not throw. */ export const TimeSeriesChart: FC = props => { - const hasData = props.points.some(point => props.series.some(series => pointValue(point, series.key) > 0)) - const chartType = props.variant ?? 'line' + const chartType = props.variant === 'column-trend' ? 'column' : props.variant ?? 'line' + const plottedSeries = useMemo(() => props.series.flatMap(definition => { + const data = props.points.map(point => pointValue(point, definition.key)) + const primary = { + color: definition.color, + data, + id: definition.key, + name: definition.label, + type: chartType, + } + if (chartType !== 'column') return [primary] + return [ + { + ...primary, + color: Highcharts.color(definition.color) + .setOpacity(0.48) + .get('rgba') as string, + }, + { + ...primary, + data: sevenDayAverage(data), + id: `${definition.key}-trend`, + linkedTo: definition.key, + marker: { enabled: data.length === 1 }, + name: `${definition.label} (7-day average)`, + tooltip: { valueDecimals: 2 }, + type: 'line' as const, + zIndex: 2, + }, + ] + }), [chartType, props.points, props.series]) + const hasData = plottedSeries.some(item => item.data.some(value => value > 0)) const options = useMemo(() => ({ accessibility: { enabled: false }, chart: { animation: false, backgroundColor: 'transparent', height: 360, + // Leave each daily bar room on small screens and long date ranges. + scrollablePlotArea: chartType === 'column' ? { + minWidth: 80 + props.points.length * (6 * props.series.length + 6), + } : undefined, spacing: [16, 12, 8, 4], type: chartType, }, @@ -71,6 +114,7 @@ export const TimeSeriesChart: FC = props => { fillOpacity: 0.14, lineWidth: 2, }, + column: { borderWidth: 0, groupPadding: 0.1, pointPadding: 0.05 }, line: { lineWidth: 3 }, series: { animation: false, @@ -78,12 +122,7 @@ export const TimeSeriesChart: FC = props => { states: { inactive: { opacity: 1 } }, }, }, - series: props.series.map(series => ({ - color: series.color, - data: props.points.map(point => pointValue(point, series.key)), - name: series.label, - type: chartType, - })) as Highcharts.SeriesOptionsType[], + series: plottedSeries as Highcharts.SeriesOptionsType[], title: { text: undefined }, tooltip: { headerFormat: '{point.key}
', @@ -109,7 +148,7 @@ export const TimeSeriesChart: FC = props => { title: { text: props.yAxisTitle }, }, }), [chartType, props.points, props.series, props.valueDecimals, props.valueSuffix, - props.xAxisTitle, props.yAxisTitle]) + props.xAxisTitle, props.yAxisTitle, plottedSeries]) if (!hasData) { return
No activity is available for this period.
@@ -124,15 +163,15 @@ export const TimeSeriesChart: FC = props => { Date - {props.series.map(series => {series.label})} + {plottedSeries.map(item => {item.name})} - {props.points.map(point => ( + {props.points.map((point, index) => ( ).date)}> {formatReportDate(String((point as Record).date))} - {props.series.map(series => ( - {pointValue(point, series.key)} + {plottedSeries.map(item => ( + {item.data[index]} ))} ))} diff --git a/src/apps/analytics/src/lib/models/analytics.models.ts b/src/apps/analytics/src/lib/models/analytics.models.ts index 92a1aa949..9b32a91f0 100644 --- a/src/apps/analytics/src/lib/models/analytics.models.ts +++ b/src/apps/analytics/src/lib/models/analytics.models.ts @@ -284,6 +284,7 @@ export interface SpaceTechReport { /** Optional during rollout against an older API; never substitute misleading zeroes. */ personas?: (SpaceTechMetrics & { persona: SpaceTechPersona })[] personaSeries?: ({ date: string } & Record)[] + dailyPersonaSeries?: ({ date: string } & Record)[] campaigns: SpaceTechGroup[] countries: SpaceTechGroup[] devices: SpaceTechGroup[] diff --git a/src/apps/analytics/src/pages/SpaceTechAnalyticsPage.spec.tsx b/src/apps/analytics/src/pages/SpaceTechAnalyticsPage.spec.tsx index 1dd1a0f96..75de7d548 100644 --- a/src/apps/analytics/src/pages/SpaceTechAnalyticsPage.spec.tsx +++ b/src/apps/analytics/src/pages/SpaceTechAnalyticsPage.spec.tsx @@ -40,15 +40,21 @@ const report = { } describe('SpaceTech Analytics', () => { - beforeEach(() => { jest.clearAllMocks(); (getSpaceTechReport as jest.Mock).mockResolvedValue(report) }) + beforeEach(() => { + jest.useFakeTimers() + jest.setSystemTime(new Date('2026-11-19T12:00:00Z')) + jest.clearAllMocks(); + (getSpaceTechReport as jest.Mock).mockResolvedValue(report) + }) + afterEach(() => { jest.useRealTimers() }) - it('loads ninety days and applies every UTM filter together', async () => { + it('loads the campaign from launch and applies every UTM filter together', async () => { render() fireEvent.click(screen.getByRole('tab', { name: 'Details' })) await screen.findByText('Submissions: 2') const initial = (getSpaceTechReport as jest.Mock).mock.calls[0][0] - expect((Date.parse(initial.to) - Date.parse(initial.from)) / 86400000) - .toBe(89) + expect(initial) + .toEqual({ from: '2026-11-05', to: '2026-11-19' }) fireEvent.change(screen.getByLabelText('utm_source'), { target: { value: 'linkedin' } }) fireEvent.change(screen.getByLabelText('utm_medium'), { target: { value: 'social' } }) fireEvent.change(screen.getByLabelText('utm_campaign'), { target: { value: 'george' } }) @@ -66,6 +72,32 @@ describe('SpaceTech Analytics', () => { .toBeInTheDocument() }) + it('retains the rolling 90-day default once the campaign is older', async () => { + jest.setSystemTime(new Date('2027-03-01T00:00:00Z')) + render() + await screen.findByText(/Latest processed event/) + expect(getSpaceTechReport) + .toHaveBeenCalledWith({ from: '2026-12-02', to: '2027-03-01' }) + }) + + it('prevents requests for pre-launch dates', async () => { + render() + await screen.findByText(/Latest processed event/) + const start = screen.getByLabelText('Start date') + expect(start) + .toHaveAttribute('min', '2026-11-05') + expect(screen.getByLabelText('End date')) + .toHaveAttribute('min', '2026-11-05') + fireEvent.change(start, { target: { value: '2026-11-04' } }) + expect(start) + .toBeInvalid() + fireEvent.submit(start.closest('form') as HTMLFormElement) + expect(screen.getByRole('alert')) + .toHaveTextContent('Choose a start date on or after November 5, 2026.') + expect(getSpaceTechReport) + .toHaveBeenCalledTimes(1) + }) + it('clears applied filters and invalid draft dates and reloads the default report', async () => { render() expect(await screen.findByText(/Latest processed event/)) @@ -108,8 +140,8 @@ describe('SpaceTech Analytics', () => { const retry = await screen.findByRole('button', { name: 'Analytics data could not be loaded. Try again.' }) fireEvent.click(retry) await screen.findByText('Submissions: 2') - fireEvent.change(screen.getByLabelText('Start date'), { target: { value: '2026-10-10' } }) - fireEvent.change(screen.getByLabelText('End date'), { target: { value: '2026-10-01' } }) + fireEvent.change(screen.getByLabelText('Start date'), { target: { value: '2026-11-10' } }) + fireEvent.change(screen.getByLabelText('End date'), { target: { value: '2026-11-09' } }) fireEvent.click(screen.getByRole('button', { name: 'Apply filters' })) expect(screen.getByRole('alert')) .toHaveTextContent('The start date must not be after the end date.') diff --git a/src/apps/analytics/src/pages/SpaceTechAnalyticsPage.tsx b/src/apps/analytics/src/pages/SpaceTechAnalyticsPage.tsx index 220e08041..0573499ca 100644 --- a/src/apps/analytics/src/pages/SpaceTechAnalyticsPage.tsx +++ b/src/apps/analytics/src/pages/SpaceTechAnalyticsPage.tsx @@ -14,6 +14,7 @@ import { SpaceTechDashboard, spaceTechMetrics as metrics } from './SpaceTechDash import SpaceTechLeads from './SpaceTechLeads' import styles from './AnalyticsPages.module.scss' +const campaignStart = '2026-11-05' const series = [ { color: '#2c5de5', key: 'visitors', label: 'Unique visitors' }, { color: '#137d60', key: 'submissions', label: 'Form submissions' }, @@ -59,14 +60,14 @@ const Breakdown: FC<{ title: string; rows: SpaceTechGroup[]; columns: string[][] ) -/** SpaceTech opens on the last 90 UTC calendar days with all attribution values included. */ +/** SpaceTech opens on up to 90 UTC calendar days of campaign activity. */ function defaultSpaceTechFilters(): SpaceTechFilters { const to = defaultAnalyticsDateRange().to const start = new Date(`${to}T00:00:00Z`) start.setUTCDate(start.getUTCDate() - 89) const from = start.toISOString() .slice(0, 10) - return { from, to } + return { from: from < campaignStart ? campaignStart : from, to } } /** Shows UTM-attributed SpaceTech traffic, engagement, and accepted form submissions. */ @@ -124,12 +125,17 @@ export const SpaceTechAnalyticsPage: FC = () => { ))} -

Traffic and accepted form submissions for /space-tech. Dates are inclusive and use UTC.

+

+ Traffic and accepted form submissions for /space-tech since November 5, 2026. + Dates are inclusive and use UTC. +

{ event.preventDefault() const validation = validateAnalyticsDateRange(draft) + || (draft.from < campaignStart + ? 'Choose a start date on or after November 5, 2026.' : undefined) setError(validation) if (!validation) applyFilters(draft) }} @@ -138,6 +144,7 @@ export const SpaceTechAnalyticsPage: FC = () => {