@tech4good/angular-schematics 21.3.0 → 21.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.t4g/agent-memory.db +0 -0
- package/CHANGELOG.md +41 -0
- package/package.json +1 -1
- package/src/entity/index.js +42 -9
- package/src/entity/index.js.map +1 -1
- package/src/entity/index_spec.js +42 -8
- package/src/entity/index_spec.js.map +1 -1
- package/src/entity/schema.json +0 -5
- package/src/ng-add/files/.firebaserc.template +2 -1
- package/src/ng-add/files/.gitignore.template +1 -0
- package/src/ng-add/files/angular.json.template +3 -0
- package/src/ng-add/files/bigquery/queries/active_time_by_route.sql.template +34 -0
- package/src/ng-add/files/bigquery/scripts/export_entities.py.template +143 -0
- package/src/ng-add/files/bigquery/scripts/run_query.py.template +167 -0
- package/src/ng-add/files/bigquery/views/events_flat.sql.template +60 -0
- package/src/ng-add/files/bigquery/views/logs_latest.sql.template +34 -0
- package/src/ng-add/files/docs-infra/analytics-guide.md.template +170 -0
- package/src/ng-add/files/firebase.logs.json.template +5 -0
- package/src/ng-add/files/firestore.indexes.json.template +89 -0
- package/src/ng-add/files/firestore.logs.rules.spec.ts.template +100 -0
- package/src/ng-add/files/firestore.logs.rules.template +8 -0
- package/src/ng-add/files/firestore.rules.spec.ts.template +88 -1
- package/src/ng-add/files/firestore.rules.template +9 -0
- package/src/ng-add/files/jest.config.ts.template +1 -1
- package/src/ng-add/files/package.json.template +6 -3
- package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-list.component.spec.ts.template +3 -3
- package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-table/admin-user-table.component.spec.ts.template +0 -1
- package/src/ng-add/files/src/app/app.component.html.template +1 -1
- package/src/ng-add/files/src/app/app.component.scss.template +9 -1
- package/src/ng-add/files/src/app/app.component.spec.ts.template +2 -2
- package/src/ng-add/files/src/app/auth-routing.spec.ts.template +1 -1
- package/src/ng-add/files/src/app/core/analytics/log.service.ts.template +27 -5
- package/src/ng-add/files/src/app/core/analytics/time-analytics.service.spec.ts.template +147 -4
- package/src/ng-add/files/src/app/core/analytics/time-analytics.service.ts.template +355 -149
- package/src/ng-add/files/src/app/core/auth/guards/require-auth-and-consent.guard.ts.template +3 -1
- package/src/ng-add/files/src/app/core/firebase/cached-listeners.service.ts.template +53 -51
- package/src/ng-add/files/src/app/core/firebase/firebase.mock.service.ts.template +6 -0
- package/src/ng-add/files/src/app/core/firebase/simulate-load.spec.ts.template +2 -2
- package/src/ng-add/files/src/app/core/firebase/simulate-stream.spec.ts.template +14 -14
- package/src/ng-add/files/src/app/core/firebase/stream-multiplexer.ts.template +50 -48
- package/src/ng-add/files/src/app/core/logging/logging.service.spec.ts.template +118 -0
- package/src/ng-add/files/src/app/core/logging/logging.service.ts.template +168 -0
- package/src/ng-add/files/src/app/core/store/app.model.ts.template +3 -1
- package/src/ng-add/files/src/app/core/store/app.store.ts.template +11 -9
- package/src/ng-add/files/src/app/core/store/auth/auth.mock.ts.template +5 -4
- package/src/ng-add/files/src/app/core/store/auth/auth.store.ts.template +13 -4
- package/src/ng-add/files/src/app/core/store/user/user.mock.ts.template +0 -4
- package/src/ng-add/files/src/app/core/store/user/user.model.ts.template +0 -1
- package/src/ng-add/files/src/app/core/store/user-private/user-private.mock.ts.template +15 -0
- package/src/ng-add/files/src/app/core/store/user-private/user-private.model.ts.template +9 -0
- package/src/ng-add/files/src/app/core/store/user-private/user-private.store.ts.template +41 -0
- package/src/ng-add/files/src/app/first-time/consent/consent.component.html.template +172 -48
- package/src/ng-add/files/src/app/first-time/consent/consent.component.scss.template +31 -0
- package/src/ng-add/files/src/app/first-time/consent/consent.component.spec.ts.template +31 -3
- package/src/ng-add/files/src/app/first-time/consent/consent.component.ts.template +12 -11
- package/src/ng-add/files/src/app/first-time/consent/consent.guard.ts.template +0 -6
- package/src/ng-add/files/src/app/first-time/early-access/early-access.component.spec.ts.template +0 -1
- package/src/ng-add/files/src/app/first-time/early-access/early-access.component.ts.template +1 -1
- package/src/ng-add/files/src/app/first-time/early-access/early-access.guard.ts.template +7 -1
- package/src/ng-add/files/src/app/first-time/first-time-routing.spec.ts.template +7 -6
- package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.ts.template +3 -3
- package/src/ng-add/files/src/app/first-time/landing/landing.component.scss.template +1 -1
- package/src/ng-add/files/src/app/first-time/onboarding/onboarding.component.ts.template +3 -3
- package/src/ng-add/files/src/app/main/home/home.component.spec.ts.template +1 -1
- package/src/ng-add/files/src/app/main/home/home.component.ts.template +4 -4
- package/src/ng-add/files/src/app/shared/dev-status-bar/dev-status-bar.component.scss.template +1 -0
- package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.service.spec.ts.template +41 -5
- package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.service.ts.template +25 -2
- package/src/ng-add/files/src/environments/environment.test.ts.template +1 -1
- package/src/shared/statements-adder.d.ts +1 -0
- package/src/shared/statements-adder.js +8 -0
- package/src/shared/statements-adder.js.map +1 -1
- package/src/ng-add/files/src/app/core/firebase/query-logger.ts.template +0 -11
- package/tech4good-angular-schematics-21.0.0.tgz +0 -0
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
-- View: events_flat
|
|
2
|
+
-- Description: Flattens the nested time segments and interactions arrays in the latest logs
|
|
3
|
+
-- into a single clean event-stream format with one row per event.
|
|
4
|
+
-- Preserves the raw chronological time segments array for advanced engagement pattern analysis.
|
|
5
|
+
|
|
6
|
+
CREATE OR REPLACE VIEW `analytics.events_flat` AS
|
|
7
|
+
-- 1. Route visits (emitted when a route is closed/navigated away from)
|
|
8
|
+
SELECT
|
|
9
|
+
document_id,
|
|
10
|
+
__userId AS user_id,
|
|
11
|
+
__sessionId AS session_id,
|
|
12
|
+
__deviceId AS device_id,
|
|
13
|
+
route,
|
|
14
|
+
_createdAt,
|
|
15
|
+
_updatedAt,
|
|
16
|
+
'route_visit' AS event_type,
|
|
17
|
+
startTime AS timestamp,
|
|
18
|
+
CAST(NULL AS STRING) AS category,
|
|
19
|
+
CAST(NULL AS STRING) AS action,
|
|
20
|
+
CAST(NULL AS STRING) AS properties,
|
|
21
|
+
-- Preserves the chronological pattern of active/rest intervals (JSON array)
|
|
22
|
+
time_segments,
|
|
23
|
+
COALESCE(
|
|
24
|
+
(SELECT SUM(CAST(JSON_VALUE(t, '$.total') AS INT64))
|
|
25
|
+
FROM UNNEST(JSON_QUERY_ARRAY(time_segments)) t
|
|
26
|
+
WHERE JSON_VALUE(t, '$.type') = 'active'),
|
|
27
|
+
0
|
|
28
|
+
) AS total_active_ms,
|
|
29
|
+
COALESCE(
|
|
30
|
+
(SELECT SUM(CAST(JSON_VALUE(t, '$.total') AS INT64))
|
|
31
|
+
FROM UNNEST(JSON_QUERY_ARRAY(time_segments)) t
|
|
32
|
+
WHERE JSON_VALUE(t, '$.type') = 'rest'),
|
|
33
|
+
0
|
|
34
|
+
) AS total_rest_ms
|
|
35
|
+
FROM
|
|
36
|
+
`analytics.logs_latest`
|
|
37
|
+
|
|
38
|
+
UNION ALL
|
|
39
|
+
|
|
40
|
+
-- 2. Interactions (discrete click, focus, and submission events)
|
|
41
|
+
SELECT
|
|
42
|
+
document_id,
|
|
43
|
+
__userId AS user_id,
|
|
44
|
+
__sessionId AS session_id,
|
|
45
|
+
__deviceId AS device_id,
|
|
46
|
+
route,
|
|
47
|
+
_createdAt,
|
|
48
|
+
_updatedAt,
|
|
49
|
+
'interaction' AS event_type,
|
|
50
|
+
CAST(JSON_VALUE(ix, '$[0]') AS INT64) AS timestamp,
|
|
51
|
+
JSON_VALUE(ix, '$[1]') AS category,
|
|
52
|
+
JSON_VALUE(ix, '$[2]') AS action,
|
|
53
|
+
JSON_VALUE(ix, '$[3]') AS properties,
|
|
54
|
+
-- Null for interactions
|
|
55
|
+
CAST(NULL AS STRING) AS time_segments,
|
|
56
|
+
CAST(NULL AS INT64) AS total_active_ms,
|
|
57
|
+
CAST(NULL AS INT64) AS total_rest_ms
|
|
58
|
+
FROM
|
|
59
|
+
`analytics.logs_latest`,
|
|
60
|
+
UNNEST(JSON_QUERY_ARRAY(interactions)) ix;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
-- View: logs_latest
|
|
2
|
+
-- Description: Extracts the latest version of each log document from the raw changelog table,
|
|
3
|
+
-- deduplicating documents that have been updated (e.g., via sendBeacon writes).
|
|
4
|
+
|
|
5
|
+
CREATE OR REPLACE VIEW `analytics.logs_latest` AS
|
|
6
|
+
SELECT
|
|
7
|
+
document_id,
|
|
8
|
+
timestamp AS bq_sync_timestamp,
|
|
9
|
+
operation,
|
|
10
|
+
JSON_VALUE(data, '$.__userId') AS __userId,
|
|
11
|
+
JSON_VALUE(data, '$.__sessionId') AS __sessionId,
|
|
12
|
+
JSON_VALUE(data, '$.__deviceId') AS __deviceId,
|
|
13
|
+
JSON_VALUE(data, '$.route') AS route,
|
|
14
|
+
CAST(JSON_VALUE(data, '$.startTime') AS INT64) AS startTime,
|
|
15
|
+
JSON_QUERY(data, '$.time') AS time_segments,
|
|
16
|
+
JSON_QUERY(data, '$.interactions') AS interactions,
|
|
17
|
+
CAST(JSON_VALUE(data, '$._createdAt') AS INT64) AS _createdAt,
|
|
18
|
+
CAST(JSON_VALUE(data, '$._updatedAt') AS INT64) AS _updatedAt
|
|
19
|
+
FROM (
|
|
20
|
+
SELECT
|
|
21
|
+
document_id,
|
|
22
|
+
timestamp,
|
|
23
|
+
operation,
|
|
24
|
+
data,
|
|
25
|
+
ROW_NUMBER() OVER (
|
|
26
|
+
PARTITION BY document_id
|
|
27
|
+
ORDER BY timestamp DESC
|
|
28
|
+
) AS rn
|
|
29
|
+
FROM
|
|
30
|
+
`analytics.logs_raw_changelog`
|
|
31
|
+
)
|
|
32
|
+
WHERE
|
|
33
|
+
rn = 1
|
|
34
|
+
AND operation != 'DELETE';
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# Analytics & Data Warehousing Guide
|
|
2
|
+
|
|
3
|
+
This document describes the telemetry logging and data warehousing architecture. It explains how user interactions are tracked, how data is synchronized to BigQuery, and how to query this data for research and analysis.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Architecture Overview
|
|
8
|
+
|
|
9
|
+
To support both real-time client-side tracking and complex research analysis (like NLP, statistical distribution, and LLM classifications), the analytics infrastructure uses a two-tier database strategy:
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
┌───────────────────────────────────────────────┐
|
|
13
|
+
│ Browser (Angular Client) │
|
|
14
|
+
│ Emits route-changes and interaction events │
|
|
15
|
+
└──────────────────────┬────────────────────────┘
|
|
16
|
+
│
|
|
17
|
+
┌─────────────▼─────────────┐
|
|
18
|
+
│ Firestore: <log-project> │
|
|
19
|
+
│ logs/{logId} │
|
|
20
|
+
└─────────────┬─────────────┘
|
|
21
|
+
│ (Firebase BigQuery Export)
|
|
22
|
+
┌─────────────▼─────────────┐
|
|
23
|
+
│ Google BigQuery │
|
|
24
|
+
│ analytics.logs_latest │ ← SQL View (latest state)
|
|
25
|
+
│ analytics.events_flat │ ← SQL View (event rows)
|
|
26
|
+
└───────────────────────────┘
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
1. **Firestore (`<log-project>` project)**: Serves as the high-volume ingestion layer. The client writes telemetry events to the `logs` collection. Firestore handles unreliable client networks, localStorage caching, retries, and browser beacon events.
|
|
30
|
+
2. **BigQuery**: Serves as the analysis database. Telemetry documents are streamed in real-time to BigQuery using the **Firestore BigQuery Export** extension. Researchers run SQL queries and Python scripts against BigQuery to calculate metrics.
|
|
31
|
+
3. **On-Demand Entity Export**: Direct application entities (like user answers or transaction records) are exported to BigQuery or Python on-demand using a Python script. This preserves privacy and makes user deletion requests trivial.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 2. In-App Telemetry & Logging
|
|
36
|
+
|
|
37
|
+
Client-side telemetry is managed by the `TimeAnalyticsService`.
|
|
38
|
+
|
|
39
|
+
### 2.1 Log Document Structure
|
|
40
|
+
Telemetry logs are written to Firestore under the collection `logs` with document IDs matching the format `${__sessionId}__${startTime}`. Each document represents a single page/route visit or registered UI state segment and contains:
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"__userId": "user_123",
|
|
45
|
+
"__sessionId": "session_abc",
|
|
46
|
+
"__deviceId": "device_xyz",
|
|
47
|
+
"route": "/practice",
|
|
48
|
+
"state": { "problemId": "prob_456" },
|
|
49
|
+
"startTime": 1720000000000,
|
|
50
|
+
"time": [
|
|
51
|
+
{ "type": "active", "total": 5200 },
|
|
52
|
+
{ "type": "rest", "total": 12000 }
|
|
53
|
+
],
|
|
54
|
+
"interactions": [
|
|
55
|
+
[1720000001000, "problem", "hint_click", "{\"hintIndex\":1}"],
|
|
56
|
+
[1720000005000, "problem", "submit_attempt", "{\"attemptText\":\"42\"}"]
|
|
57
|
+
],
|
|
58
|
+
"_createdAt": 1720000000000,
|
|
59
|
+
"_updatedAt": 1720000006000
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
* **`route` & `state`**: Tracks current URL route and optional registered UI state dimensions (e.g. `state.problemId`).
|
|
64
|
+
* **`time` array**: Tracks accumulated active and rest time on the route/state segment (measured using window focus, visibility, and mouse/keyboard activity).
|
|
65
|
+
* **`interactions` array**: Custom events tracked during the visit. Each interaction is a tuple: `[timestamp, category, action, JSON_stringified_properties]`.
|
|
66
|
+
* **`_createdAt` & `_updatedAt`**: Client-side epoch timestamps (in milliseconds) capturing when the log was opened and when it was last written (including beacon overwrites on tab close).
|
|
67
|
+
|
|
68
|
+
### 2.2 Registering UI State Dimensions (`registerState`)
|
|
69
|
+
By default, logs are flushed when route or user changes. For components where users remain on a single route across multiple distinct items (such as solving math problems on `/practice`), components register state signals with `TimeAnalyticsService`:
|
|
70
|
+
|
|
71
|
+
```typescript
|
|
72
|
+
// In component constructor
|
|
73
|
+
this.analytics.registerState(
|
|
74
|
+
'problemId',
|
|
75
|
+
computed(() => this.currentProgress()?.__currentProblemId ?? null),
|
|
76
|
+
this.injector
|
|
77
|
+
);
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
* **Behavior:** When the registered state signal value changes, `TimeAnalyticsService` flushes the current log segment to Firestore and starts a new segment for the new state value.
|
|
81
|
+
* **Cleanup:** State registrations are automatically cleaned up when the component is destroyed via `DestroyRef`.
|
|
82
|
+
* **Usage Rule:** Register state sparingly — only for dimensions requiring first-class time segmentation (e.g., `problemId`). General user interactions should be logged via `trackInteraction()`.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 3. Configuring BigQuery Sync
|
|
87
|
+
|
|
88
|
+
To stream logs from Firestore to BigQuery, you must install the **Firestore BigQuery Export** extension on your logs Firebase project.
|
|
89
|
+
|
|
90
|
+
### 3.1 Installation Steps
|
|
91
|
+
1. In the Firebase Console, navigate to **Extensions**.
|
|
92
|
+
2. Search for **Firestore BigQuery Export** and click **Install**.
|
|
93
|
+
3. Configure the extension with the following parameters:
|
|
94
|
+
- **Collection path**: `logs`
|
|
95
|
+
- **Dataset ID**: `analytics`
|
|
96
|
+
- **Table ID**: `logs_raw`
|
|
97
|
+
- **Cloud Function location**: Select the region closest to your Firestore database (e.g., `us-central1`).
|
|
98
|
+
4. Give the generated service account permissions to write to BigQuery.
|
|
99
|
+
|
|
100
|
+
The extension will create a BigQuery dataset named `analytics` containing:
|
|
101
|
+
* `logs_raw_changelog`: A table that appends a new row on every Firestore document create, update, or delete.
|
|
102
|
+
* `logs_raw_schema`: Internal schema helper table.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 4. Understanding the BigQuery Changelog
|
|
107
|
+
|
|
108
|
+
Because BigQuery is an append-only warehouse, the extension does not edit existing rows. If a user's browser updates a log document (e.g. adding time via `sendBeacon` when they close the tab), a new row is appended to `logs_raw_changelog`.
|
|
109
|
+
|
|
110
|
+
Each row in `logs_raw_changelog` has the following system columns:
|
|
111
|
+
* `document_id`: The Firestore document path (`logs/sessionId__startTime`).
|
|
112
|
+
* `timestamp`: When the write was synced to BigQuery.
|
|
113
|
+
* `operation`: The Firestore write operation: `IMPORT`, `CREATE`, `UPDATE`, or `DELETE`.
|
|
114
|
+
* `data`: A JSON string containing the full serialized Firestore document.
|
|
115
|
+
|
|
116
|
+
To query the current state of logs without duplicates, we use a SQL view that filters for the latest update per document.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## 5. SQL Views & Queries
|
|
121
|
+
|
|
122
|
+
The SQL view files are located in `/bigquery/views/` and `/bigquery/queries/`.
|
|
123
|
+
|
|
124
|
+
### 5.1 No Project Prefixes Needed
|
|
125
|
+
Our SQL scripts are designed **relativity** (omitting the GCP Project ID prefix, e.g. using `analytics.events_flat` instead of `your_project.analytics.events_flat`).
|
|
126
|
+
This means they run cleanly out of the box in the BigQuery Web Console (which executes them in your active project workspace) or via terminal scripts.
|
|
127
|
+
|
|
128
|
+
### 5.2 Deduplicating Logs (`logs_latest`)
|
|
129
|
+
The view `logs_latest` extracts only the latest state of each document:
|
|
130
|
+
```sql
|
|
131
|
+
SELECT * FROM `analytics.logs_latest` LIMIT 10;
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### 5.3 Flattening Telemetry (`events_flat`)
|
|
135
|
+
The `events_flat` view flattens time segments and interactions nested arrays into standard tabular rows. Every row in `events_flat` represents a discrete event, typed as either:
|
|
136
|
+
- `route_visit`: Emitted when the user navigates away from a route. Includes columns `total_active_ms`, `total_rest_ms`, and `time_segments` (a raw JSON array containing the chronological sequence of active/idle intervals for pattern analysis).
|
|
137
|
+
- `interaction`: Emitted for custom telemetry actions. Includes columns `category`, `action`, and `properties` (parsed JSON).
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## 6. Running Queries & Exports via Terminal
|
|
142
|
+
|
|
143
|
+
To avoid browser copy-paste workflows and support data analyses, we provide terminal scripts inside `bigquery/scripts/`.
|
|
144
|
+
|
|
145
|
+
### 6.1 Running SQL Queries (`run_query.py`)
|
|
146
|
+
Use `run_query.py` to run any SQL file from the terminal and export the results to **JSON**, **CSV**, or a local **SQLite database**.
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
# Export active time statistics by route to a local JSON file
|
|
150
|
+
python bigquery/scripts/run_query.py --project <your-gcp-project-id> --query bigquery/queries/active_time_by_route.sql --output output.json
|
|
151
|
+
|
|
152
|
+
# Export active time statistics by route to a local CSV file
|
|
153
|
+
python bigquery/scripts/run_query.py --project <your-gcp-project-id> --query bigquery/queries/active_time_by_route.sql --output output.csv
|
|
154
|
+
|
|
155
|
+
# Export active time statistics by route directly into a local SQLite table named 'active_time'
|
|
156
|
+
python bigquery/scripts/run_query.py --project <your-gcp-project-id> --query bigquery/queries/active_time_by_route.sql --output stats.db --table active_time
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### 6.2 On-Demand Entity Export (`export_entities.py`)
|
|
160
|
+
Application entities contain sensitive data and are not automatically synchronized to BigQuery. Use `export_entities.py` to pull these collections directly from Firestore to local files on-demand for research.
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
# Export documents directly from Firestore to a local JSON file
|
|
164
|
+
python bigquery/scripts/export_entities.py --credentials path/to/key.json --collection <collection-name> --output data.json
|
|
165
|
+
|
|
166
|
+
# Export documents to a local CSV file (auto-flattens nested fields)
|
|
167
|
+
python bigquery/scripts/export_entities.py --credentials path/to/key.json --collection <collection-name> --output data.csv
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
*Note: If `--credentials` is omitted, the scripts automatically search the environment for `GOOGLE_APPLICATION_CREDENTIALS` or Application Default Credentials.*
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
{
|
|
2
|
+
"indexes": [
|
|
3
|
+
{
|
|
4
|
+
"collectionGroup": "users",
|
|
5
|
+
"queryScope": "COLLECTION",
|
|
6
|
+
"fields": [
|
|
7
|
+
{
|
|
8
|
+
"fieldPath": "_deleted",
|
|
9
|
+
"order": "ASCENDING"
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"fieldPath": "accessState",
|
|
13
|
+
"order": "ASCENDING"
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"fieldPath": "joinedWaitlistAt",
|
|
17
|
+
"order": "ASCENDING"
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"fieldPath": "__name__",
|
|
21
|
+
"order": "ASCENDING"
|
|
22
|
+
}
|
|
23
|
+
],
|
|
24
|
+
"density": "SPARSE_ALL"
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"collectionGroup": "users",
|
|
28
|
+
"queryScope": "COLLECTION",
|
|
29
|
+
"fields": [
|
|
30
|
+
{
|
|
31
|
+
"fieldPath": "accessState",
|
|
32
|
+
"order": "ASCENDING"
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"fieldPath": "_createdAt",
|
|
36
|
+
"order": "ASCENDING"
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
"fieldPath": "__name__",
|
|
40
|
+
"order": "ASCENDING"
|
|
41
|
+
}
|
|
42
|
+
],
|
|
43
|
+
"density": "SPARSE_ALL"
|
|
44
|
+
},
|
|
45
|
+
{
|
|
46
|
+
"collectionGroup": "users",
|
|
47
|
+
"queryScope": "COLLECTION",
|
|
48
|
+
"fields": [
|
|
49
|
+
{
|
|
50
|
+
"fieldPath": "accessState",
|
|
51
|
+
"order": "ASCENDING"
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
"fieldPath": "_updatedAt",
|
|
55
|
+
"order": "DESCENDING"
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
"fieldPath": "__name__",
|
|
59
|
+
"order": "DESCENDING"
|
|
60
|
+
}
|
|
61
|
+
],
|
|
62
|
+
"density": "SPARSE_ALL"
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
"collectionGroup": "users",
|
|
66
|
+
"queryScope": "COLLECTION",
|
|
67
|
+
"fields": [
|
|
68
|
+
{
|
|
69
|
+
"fieldPath": "__id",
|
|
70
|
+
"order": "ASCENDING"
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"fieldPath": "_deleted",
|
|
74
|
+
"order": "ASCENDING"
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"fieldPath": "_updatedAt",
|
|
78
|
+
"order": "ASCENDING"
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
"fieldPath": "__name__",
|
|
82
|
+
"order": "ASCENDING"
|
|
83
|
+
}
|
|
84
|
+
],
|
|
85
|
+
"density": "SPARSE_ALL"
|
|
86
|
+
}
|
|
87
|
+
],
|
|
88
|
+
"fieldOverrides": []
|
|
89
|
+
}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @jest-environment node
|
|
3
|
+
*/
|
|
4
|
+
import {
|
|
5
|
+
assertFails,
|
|
6
|
+
assertSucceeds,
|
|
7
|
+
initializeTestEnvironment,
|
|
8
|
+
RulesTestEnvironment,
|
|
9
|
+
} from '@firebase/rules-unit-testing';
|
|
10
|
+
import { readFileSync } from 'fs';
|
|
11
|
+
import { doc, setDoc, updateDoc, getDoc, deleteDoc } from 'firebase/firestore';
|
|
12
|
+
|
|
13
|
+
let testEnv: RulesTestEnvironment;
|
|
14
|
+
|
|
15
|
+
beforeAll(async () => {
|
|
16
|
+
testEnv = await initializeTestEnvironment({
|
|
17
|
+
projectId: 'demo-logs-rules-test',
|
|
18
|
+
firestore: {
|
|
19
|
+
rules: readFileSync('firestore.logs.rules', 'utf8'),
|
|
20
|
+
host: '127.0.0.1',
|
|
21
|
+
port: 8080,
|
|
22
|
+
},
|
|
23
|
+
});
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
afterEach(async () => {
|
|
27
|
+
await testEnv.clearFirestore();
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
afterAll(async () => {
|
|
31
|
+
await testEnv.cleanup();
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
describe('Firestore Logs Security Rules', () => {
|
|
35
|
+
it('should allow anyone (unauthenticated) to create and update logs', async () => {
|
|
36
|
+
const unauthedDb = testEnv.unauthenticatedContext().firestore();
|
|
37
|
+
const logDoc = doc(unauthedDb, 'logs/log_123');
|
|
38
|
+
|
|
39
|
+
// Create log
|
|
40
|
+
await assertSucceeds(
|
|
41
|
+
setDoc(logDoc, {
|
|
42
|
+
__sessionId: 'session_abc',
|
|
43
|
+
route: '/s/session_1',
|
|
44
|
+
startTime: Date.now(),
|
|
45
|
+
})
|
|
46
|
+
);
|
|
47
|
+
|
|
48
|
+
// Update log
|
|
49
|
+
await assertSucceeds(
|
|
50
|
+
updateDoc(logDoc, {
|
|
51
|
+
_updatedAt: Date.now(),
|
|
52
|
+
})
|
|
53
|
+
);
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
it('should allow authenticated users to create and update logs', async () => {
|
|
57
|
+
const authDb = testEnv.authenticatedContext('student_1').firestore();
|
|
58
|
+
const logDoc = doc(authDb, 'logs/log_456');
|
|
59
|
+
|
|
60
|
+
// Create log
|
|
61
|
+
await assertSucceeds(
|
|
62
|
+
setDoc(logDoc, {
|
|
63
|
+
__sessionId: 'session_abc',
|
|
64
|
+
route: '/s/session_1',
|
|
65
|
+
startTime: Date.now(),
|
|
66
|
+
})
|
|
67
|
+
);
|
|
68
|
+
|
|
69
|
+
// Update log
|
|
70
|
+
await assertSucceeds(
|
|
71
|
+
updateDoc(logDoc, {
|
|
72
|
+
_updatedAt: Date.now(),
|
|
73
|
+
})
|
|
74
|
+
);
|
|
75
|
+
});
|
|
76
|
+
|
|
77
|
+
it('should deny anyone from reading logs', async () => {
|
|
78
|
+
const unauthedDb = testEnv.unauthenticatedContext().firestore();
|
|
79
|
+
const authDb = testEnv.authenticatedContext('student_1').firestore();
|
|
80
|
+
|
|
81
|
+
await testEnv.withSecurityRulesDisabled(async (context) => {
|
|
82
|
+
await setDoc(doc(context.firestore(), 'logs/log_123'), { data: 'private' });
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
await assertFails(getDoc(doc(unauthedDb, 'logs/log_123')));
|
|
86
|
+
await assertFails(getDoc(doc(authDb, 'logs/log_123')));
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
it('should deny anyone from deleting logs', async () => {
|
|
90
|
+
const unauthedDb = testEnv.unauthenticatedContext().firestore();
|
|
91
|
+
const authDb = testEnv.authenticatedContext('student_1').firestore();
|
|
92
|
+
|
|
93
|
+
await testEnv.withSecurityRulesDisabled(async (context) => {
|
|
94
|
+
await setDoc(doc(context.firestore(), 'logs/log_123'), { data: 'private' });
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
await assertFails(deleteDoc(doc(unauthedDb, 'logs/log_123')));
|
|
98
|
+
await assertFails(deleteDoc(doc(authDb, 'logs/log_123')));
|
|
99
|
+
});
|
|
100
|
+
});
|
|
@@ -8,7 +8,7 @@ import {
|
|
|
8
8
|
RulesTestEnvironment,
|
|
9
9
|
} from '@firebase/rules-unit-testing';
|
|
10
10
|
import { readFileSync } from 'fs';
|
|
11
|
-
import { doc, setDoc, updateDoc, getDoc, deleteDoc, collection, addDoc } from 'firebase/firestore';
|
|
11
|
+
import { doc, setDoc, updateDoc, getDoc, deleteDoc, collection, addDoc, query, where, getDocs } from 'firebase/firestore';
|
|
12
12
|
|
|
13
13
|
let testEnv: RulesTestEnvironment;
|
|
14
14
|
|
|
@@ -138,6 +138,16 @@ describe('Firestore Security Rules', () => {
|
|
|
138
138
|
const adminDb = testEnv.authenticatedContext('admin').firestore();
|
|
139
139
|
await assertSucceeds(deleteDoc(doc(adminDb, 'users/alice')));
|
|
140
140
|
});
|
|
141
|
+
|
|
142
|
+
it('should allow authenticated users to list users', async () => {
|
|
143
|
+
const aliceDb = testEnv.authenticatedContext('alice').firestore();
|
|
144
|
+
await assertSucceeds(getDocs(collection(aliceDb, 'users')));
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
it('should deny unauthenticated users from listing users', async () => {
|
|
148
|
+
const unauthedDb = testEnv.unauthenticatedContext().firestore();
|
|
149
|
+
await assertFails(getDocs(collection(unauthedDb, 'users')));
|
|
150
|
+
});
|
|
141
151
|
});
|
|
142
152
|
|
|
143
153
|
describe('UserContexts Collection', () => {
|
|
@@ -211,6 +221,83 @@ describe('Firestore Security Rules', () => {
|
|
|
211
221
|
});
|
|
212
222
|
});
|
|
213
223
|
|
|
224
|
+
describe('UserPrivates Collection', () => {
|
|
225
|
+
it('should allow authenticated users to create their own private record', async () => {
|
|
226
|
+
const aliceDb = testEnv.authenticatedContext('alice').firestore();
|
|
227
|
+
await assertSucceeds(
|
|
228
|
+
setDoc(doc(aliceDb, 'userPrivates/alice'), {
|
|
229
|
+
email: 'alice@example.com',
|
|
230
|
+
})
|
|
231
|
+
);
|
|
232
|
+
});
|
|
233
|
+
|
|
234
|
+
it('should deny authenticated users from creating another users private record', async () => {
|
|
235
|
+
const aliceDb = testEnv.authenticatedContext('alice').firestore();
|
|
236
|
+
await assertFails(
|
|
237
|
+
setDoc(doc(aliceDb, 'userPrivates/bob'), {
|
|
238
|
+
email: 'bob@example.com',
|
|
239
|
+
})
|
|
240
|
+
);
|
|
241
|
+
});
|
|
242
|
+
|
|
243
|
+
it('should allow authenticated users to read their own private record', async () => {
|
|
244
|
+
await testEnv.withSecurityRulesDisabled(async (context) => {
|
|
245
|
+
await setDoc(doc(context.firestore(), 'userPrivates/alice'), { email: 'alice@example.com' });
|
|
246
|
+
});
|
|
247
|
+
const aliceDb = testEnv.authenticatedContext('alice').firestore();
|
|
248
|
+
await assertSucceeds(getDoc(doc(aliceDb, 'userPrivates/alice')));
|
|
249
|
+
});
|
|
250
|
+
|
|
251
|
+
it('should deny authenticated users from reading another users private record', async () => {
|
|
252
|
+
await testEnv.withSecurityRulesDisabled(async (context) => {
|
|
253
|
+
await setDoc(doc(context.firestore(), 'userPrivates/alice'), { email: 'alice@example.com' });
|
|
254
|
+
});
|
|
255
|
+
const bobDb = testEnv.authenticatedContext('bob').firestore();
|
|
256
|
+
await assertFails(getDoc(doc(bobDb, 'userPrivates/alice')));
|
|
257
|
+
});
|
|
258
|
+
|
|
259
|
+
it('should allow admin to read another users private record', async () => {
|
|
260
|
+
await testEnv.withSecurityRulesDisabled(async (context) => {
|
|
261
|
+
await setDoc(doc(context.firestore(), 'users/admin'), { isAdmin: true });
|
|
262
|
+
await setDoc(doc(context.firestore(), 'userPrivates/alice'), { email: 'alice@example.com' });
|
|
263
|
+
});
|
|
264
|
+
const adminDb = testEnv.authenticatedContext('admin').firestore();
|
|
265
|
+
await assertSucceeds(getDoc(doc(adminDb, 'userPrivates/alice')));
|
|
266
|
+
});
|
|
267
|
+
|
|
268
|
+
it('should allow authenticated users to update their own private record', async () => {
|
|
269
|
+
await testEnv.withSecurityRulesDisabled(async (context) => {
|
|
270
|
+
await setDoc(doc(context.firestore(), 'userPrivates/alice'), { email: 'alice@example.com' });
|
|
271
|
+
});
|
|
272
|
+
const aliceDb = testEnv.authenticatedContext('alice').firestore();
|
|
273
|
+
await assertSucceeds(updateDoc(doc(aliceDb, 'userPrivates/alice'), { email: 'alice2@example.com' }));
|
|
274
|
+
});
|
|
275
|
+
|
|
276
|
+
it('should deny authenticated users from updating another users private record', async () => {
|
|
277
|
+
await testEnv.withSecurityRulesDisabled(async (context) => {
|
|
278
|
+
await setDoc(doc(context.firestore(), 'userPrivates/alice'), { email: 'alice@example.com' });
|
|
279
|
+
});
|
|
280
|
+
const bobDb = testEnv.authenticatedContext('bob').firestore();
|
|
281
|
+
await assertFails(updateDoc(doc(bobDb, 'userPrivates/alice'), { email: 'alice2@example.com' }));
|
|
282
|
+
});
|
|
283
|
+
|
|
284
|
+
it('should allow authenticated users to delete their own private record', async () => {
|
|
285
|
+
await testEnv.withSecurityRulesDisabled(async (context) => {
|
|
286
|
+
await setDoc(doc(context.firestore(), 'userPrivates/alice'), { email: 'alice@example.com' });
|
|
287
|
+
});
|
|
288
|
+
const aliceDb = testEnv.authenticatedContext('alice').firestore();
|
|
289
|
+
await assertSucceeds(deleteDoc(doc(aliceDb, 'userPrivates/alice')));
|
|
290
|
+
});
|
|
291
|
+
|
|
292
|
+
it('should deny authenticated users from deleting another users private record', async () => {
|
|
293
|
+
await testEnv.withSecurityRulesDisabled(async (context) => {
|
|
294
|
+
await setDoc(doc(context.firestore(), 'userPrivates/alice'), { email: 'alice@example.com' });
|
|
295
|
+
});
|
|
296
|
+
const bobDb = testEnv.authenticatedContext('bob').firestore();
|
|
297
|
+
await assertFails(deleteDoc(doc(bobDb, 'userPrivates/alice')));
|
|
298
|
+
});
|
|
299
|
+
});
|
|
300
|
+
|
|
214
301
|
describe('Default Deny', () => {
|
|
215
302
|
it('should deny read/write to unknown collections', async () => {
|
|
216
303
|
const aliceDb = testEnv.authenticatedContext('alice').firestore();
|
|
@@ -39,6 +39,15 @@ service cloud.firestore {
|
|
|
39
39
|
&& (request.auth.uid == userId || isAdmin());
|
|
40
40
|
}
|
|
41
41
|
|
|
42
|
+
// ─── User Privates ───────────────────────────────────────────────────
|
|
43
|
+
// Create/Read/Update/Delete: only the user themselves (document ID == auth.uid) or admins
|
|
44
|
+
match /userPrivates/{userId} {
|
|
45
|
+
allow create: if request.auth != null && request.auth.uid == userId;
|
|
46
|
+
allow read: if request.auth != null && (request.auth.uid == userId || isAdmin());
|
|
47
|
+
allow update: if request.auth != null && (request.auth.uid == userId || isAdmin());
|
|
48
|
+
allow delete: if request.auth != null && (request.auth.uid == userId || isAdmin());
|
|
49
|
+
}
|
|
50
|
+
|
|
42
51
|
// ─── User Contexts ───────────────────────────────────────────────────
|
|
43
52
|
// Create: only the user themselves (auth.uid == __userId)
|
|
44
53
|
// Read: only the user themselves or admins
|
|
@@ -60,7 +60,7 @@ const config: Config = {
|
|
|
60
60
|
'/node_modules/',
|
|
61
61
|
'/dist/',
|
|
62
62
|
'<rootDir>/src/environments/environment.test.ts',
|
|
63
|
-
...(process.env['JEST_RULES'] ? [] : ['<rootDir>/firestore.rules.spec.ts'])
|
|
63
|
+
...(process.env['JEST_RULES'] ? [] : ['<rootDir>/firestore.rules.spec.ts', '<rootDir>/firestore.logs.rules.spec.ts'])
|
|
64
64
|
],
|
|
65
65
|
collectCoverageFrom: [
|
|
66
66
|
'src/app/**/*.ts',
|
|
@@ -10,11 +10,14 @@
|
|
|
10
10
|
"test": "jest",
|
|
11
11
|
"test:watch": "jest --watch",
|
|
12
12
|
"test:coverage": "jest --coverage",
|
|
13
|
-
"test:rules": "firebase emulators:exec --only firestore 'JEST_RULES=1 jest firestore.rules.spec.ts'",
|
|
13
|
+
"test:rules": "firebase emulators:exec --only firestore 'JEST_RULES=1 jest firestore.rules.spec.ts firestore.logs.rules.spec.ts'",
|
|
14
14
|
"lint": "ng lint",
|
|
15
15
|
"lintfix": "ng lint --fix",
|
|
16
16
|
"code-check": "ngc --noEmit && sass src:dist/css-check --no-source-map && rm -rf dist/css-check && npm run lintfix",
|
|
17
|
-
"analyze": "ng build --stats-json && esbuild-visualizer --metadata dist/<%= dasherize(project) %>/stats.json --filename dist/<%= dasherize(project) %>/bundle-analysis.html && open dist/<%= dasherize(project) %>/bundle-analysis.html"
|
|
17
|
+
"analyze": "ng build --stats-json && esbuild-visualizer --metadata dist/<%= dasherize(project) %>/stats.json --filename dist/<%= dasherize(project) %>/bundle-analysis.html && open dist/<%= dasherize(project) %>/bundle-analysis.html",
|
|
18
|
+
"deploy:dev": "ng build --configuration development && firebase deploy --project dev",
|
|
19
|
+
"deploy:prod": "ng build --configuration production && firebase deploy --project prod",
|
|
20
|
+
"deploy:logs": "firebase deploy --only firestore:rules --project log --config firebase.logs.json"
|
|
18
21
|
},
|
|
19
22
|
"private": true,
|
|
20
23
|
"dependencies": {
|
|
@@ -53,7 +56,7 @@
|
|
|
53
56
|
"@firebase/rules-unit-testing": "^5.0.1",
|
|
54
57
|
"firebase-tools": "^14.27.0",
|
|
55
58
|
"@ngx-env/builder": "^21.0.1",
|
|
56
|
-
"@tech4good/angular-schematics": "^21.
|
|
59
|
+
"@tech4good/angular-schematics": "^21.5.0",
|
|
57
60
|
"@types/estree": "^1.0.0",
|
|
58
61
|
"@types/jest": "^30.0.0",
|
|
59
62
|
"@types/node": "^18.19.47",
|
|
@@ -66,11 +66,11 @@ describe('AdminUserListComponent', () => {
|
|
|
66
66
|
|
|
67
67
|
// Wait for streams to populate and display user rows
|
|
68
68
|
expect(await screen.findByText('Alice Waiting')).toBeVisible();
|
|
69
|
-
expect(screen.
|
|
69
|
+
expect(await screen.findByText('Bob Done')).toBeVisible();
|
|
70
70
|
|
|
71
71
|
// Verify user context data is rendered (questionOne / questionTwo) with findByText to allow async resolution
|
|
72
|
-
expect(await screen.findByText('
|
|
73
|
-
expect(screen.
|
|
72
|
+
expect(await screen.findByText('Response to question one')).toBeVisible();
|
|
73
|
+
expect(await screen.findByText('Response to question two')).toBeVisible();
|
|
74
74
|
});
|
|
75
75
|
|
|
76
76
|
it('should handle pagination limit state updates when clicking Load More', async () => {
|