Consent Receipt, Webhook, and Analytics Operations
services/us-api/src/services/consentService.ts, services/us-api/src/webhooks/webhookService.ts, services/us-api/src/routes/internalAnalytics.ts, services/us-api/src/jobs/dailyPsuConsentMetrics.ts, services/us-api/src/jobs/psuConsentTimeoutWatchdog.ts, services/us-api/src/jobs/featureDriftJob.ts, services/us-api/src/jobs/retrainTriggerJob.ts, services/us-api/src/services/modelGovernanceService.ts, services/us-api/test/psuConsentAnalytics.test.ts
Overview
This part of the US API turns the consent domain into an operational system instead of a simple record store. It produces consent receipts, records consent and token lifecycle audit logs, signs and dispatches partner webhooks, ingests PSU consent-funnel events, and runs scheduled jobs that roll up metrics, detect timeout conditions, and watch for feature drift or retraining triggers.
The user-visible effect is that consent state changes are traceable, partner integrations receive signed callbacks, and the platform can measure where consent flows fail or stall. The operational jobs also feed model-governance workflows, so the consent pipeline directly informs downstream risk and retraining decisions.
Architecture Overview
flowchart TB
subgraph ConsentDomain [Consent Management Domain]
ConsentService[consentService ts]
WebhookService[webhookService ts]
InternalAnalyticsRoutes[internalAnalytics ts]
DailyMetricsJob[dailyPsuConsentMetrics ts]
TimeoutWatchdog[psuConsentTimeoutWatchdog ts]
FeatureDriftJob[featureDriftJob ts]
RetrainTriggerJob[retrainTriggerJob ts]
ModelGovernanceService[modelGovernanceService ts]
end
subgraph Persistence [PostgreSQL and Prisma]
ConsentTable[consent]
ConsentLogTable[consentLog]
TokenTable[token]
WebhookEndpointTable[webhookEndpoint]
WebhookDeliveryTable[webhookDelivery]
AnalyticsEvents[analytics psu consent events]
AnalyticsSessions[analytics psu consent sessions]
DailyMetrics[analytics psu consent daily metrics]
FeatureBaseline[featureDriftBaseline]
EvidenceSnapshot[evidenceSnapshot]
DriftReport[featureDriftReport]
RetrainTrigger[retrainTrigger]
ModelPerformance[modelPerformanceSnapshot]
FeatureSchemaVersion[featureSchemaVersion]
ModelArtifact[modelArtifact]
ModelDeployment[modelDeployment]
end
ConsentService --> ConsentLogTable
ConsentService --> TokenTable
ConsentService --> WebhookService
ConsentService --> ConsentTable
WebhookService --> WebhookEndpointTable
WebhookService --> WebhookDeliveryTable
InternalAnalyticsRoutes --> AnalyticsEvents
InternalAnalyticsRoutes --> AnalyticsSessions
InternalAnalyticsRoutes --> DailyMetrics
DailyMetricsJob --> AnalyticsDailyRefresh[refreshDailyMetricsForRange]
TimeoutWatchdog --> AnalyticsSessions
TimeoutWatchdog --> AnalyticsEvents
FeatureDriftJob --> ModelGovernanceService
RetrainTriggerJob --> ModelGovernanceService
ModelGovernanceService --> FeatureSchemaVersion
ModelGovernanceService --> EvidenceSnapshot
ModelGovernanceService --> FeatureBaseline
ModelGovernanceService --> DriftReport
ModelGovernanceService --> ModelPerformance
ModelGovernanceService --> RetrainTrigger
ModelGovernanceService --> ModelArtifact
ModelGovernanceService --> ModelDeployment
Component Structure
Consent Receipts and Consent Lifecycle
consentService.ts
services/us-api/src/services/consentService.ts
This service owns consent creation, revocation, receipt generation, and active-consent checks. It also writes consentLog rows for lifecycle events and triggers partner webhooks when consent is activated or revoked through token exchange or revocation flows.
| Method | Description | Returns |
|---|---|---|
createConsent |
Creates a new consent row, assigns expiry, stores refresh settings, and appends a consentLog entry with CREATED. |
Promise<Consent> |
revokeConsent |
Marks the consent as REVOKED, revokes related tokens, disconnects related connections, logs REVOKED, and tries to notify the partner with consent_revoked. |
Promise<{ consentId: string }> |
getConsentReceipt |
Builds the consent receipt directly from the current consent row. | Promise<{ consent_id: string; status: string; purpose: Purpose; data_categories: DataCategory[]; consent_disclosure_version: string; expires_at: string; created_at: string; }> |
ensureConsentActive |
Loads the consent row and rejects revoked or expired consent with CONSENT_REVOKED. |
Promise<Consent> |
CreateConsentPayload
services/us-api/src/services/consentService.ts
| Property | Type | Description |
|---|---|---|
user |
{ country: 'US'; user_reference?: string } |
Consent subject identity details. |
purpose |
Purpose |
Consent purpose stored on the consent row. |
data_categories |
DataCategory[] |
Approved data categories. |
access_duration_days |
`number \ | undefined` |
expires_at |
`string \ | undefined` |
refresh_permissions |
`{ enabled: boolean; max_refresh_per_day: number } \ | undefined` |
consent_disclosure_version |
string |
Disclosure version persisted on the consent record. |
Consent audit trail
The lifecycle methods create the durable audit records that underpin receipts:
createConsentwrites aconsentLogrow withaction: 'CREATED'.revokeConsentwrites aconsentLogrow withaction: 'REVOKED'.exchangeTokenwrites aconsentLogrow withaction: 'TOKEN_ISSUED'.
tokenService.ts
services/us-api/src/services/tokenService.ts
This service exchanges, refreshes, and introspects consent-bound tokens. It also emits webhook notifications when a pending consent becomes active.
| Method | Description | Returns |
|---|---|---|
exchangeToken |
Validates the optional link token, activates pending consent, issues access and refresh tokens, logs token issuance, and dispatches consent_activated when activation occurs. |
Promise<TokenPair> |
refreshToken |
Validates the refresh token hash, checks consent status and expiry, enforces refresh limits, and issues a new token pair. | Promise<TokenPair> |
introspectToken |
Verifies the JWT and checks token revocation state in persistence. | Promise<{ active: boolean; consent_id?: string; purpose?: Purpose; data_categories?: DataCategory[]; expires_at?: string; }> |
TokenPair
services/us-api/src/services/tokenService.ts
| Property | Type | Description |
|---|---|---|
access_token |
string |
RS256 access token issued to the client. |
refresh_token |
string |
Opaque refresh token stored as a hash. |
expires_in |
number |
Access token TTL in seconds. |
scope |
{ purpose: Purpose; data_categories: DataCategory[] } |
Token scope mirrored from the consent record. |
dispatchWebhook lifecycle coupling
exchangeToken and revokeConsent both call dispatchWebhook, but their webhook failures are swallowed by the caller. That keeps consent state changes moving even if partner delivery fails.
Signed Partner Webhooks
webhookService.ts
services/us-api/src/webhooks/webhookService.ts
This service finds active webhook endpoints for a partner, creates delivery records, signs the payload, and posts the callback. Each attempt is persisted so webhook delivery can be audited independently of consent state.
| Method | Description | Returns |
|---|---|---|
dispatchWebhook |
Loads active endpoints for the partner, creates webhookDelivery rows, signs the payload, posts the event, and marks each delivery as DELIVERED or FAILED. |
Promise<void> |
signPayload |
Produces the HMAC-SHA256 signature used in X-Webhook-Signature. |
string |
WebhookEvent
services/us-api/src/webhooks/webhookService.ts
| Property | Type | Description |
|---|---|---|
event |
string |
Partner-facing event name such as consent_activated or consent_revoked. |
payload |
Record<string, unknown> |
Event payload sent in the callback body. |
Webhook delivery record flow
[!NOTE]
signPayloadsignsevent.payload, whiledispatchWebhooksends{ event, data: event.payload }. The code does not sign the outer envelope, so webhook verification must target the inner payload format used bysignPayload.
- Delivery IDs are generated as
whd_<hex>. - The same delivery ID is used as the database primary key and as the
Idempotency-Keyheader. - Headers sent to the partner are:
Content-Type: application/jsonX-Webhook-SignatureIdempotency-Key
- Delivery status is updated after the HTTP response:
DELIVEREDwhenresponse.okis trueFAILEDotherwise
Consent Funnel Analytics Ingestion
internalAnalytics.ts
services/us-api/src/routes/internalAnalytics.ts
This route layer accepts internal event ingestion and analytics reads for PSU consent journeys. Both endpoints are protected by requireInternalAuth and validate inputs with zod before touching persistence.
| Method | Description | Returns |
|---|---|---|
registerInternalAnalyticsRoutes |
Registers the internal analytics ingestion and metrics endpoints on the Fastify app. | Promise<void> |
eventSchema
services/us-api/src/routes/internalAnalytics.ts
| Property | Type | Description |
|---|---|---|
psu_id |
string |
PSU identifier for the consent session. |
consent_session_id |
string |
Analytics session key. |
product |
string |
Product label for the flow. |
country |
string |
Country code or country label used by analytics. |
provider |
string |
Bank or provider label. |
institution_id |
`string \ | null \ |
timestamp |
string |
ISO timestamp. |
failure_reason |
`string \ | null \ |
event_name |
ConsentEventNames |
Valid consent event name. |
metricsQuerySchema
services/us-api/src/routes/internalAnalytics.ts
| Property | Type | Description |
|---|---|---|
start_date |
string |
Required date in YYYY-MM-DD format. |
end_date |
string |
Required date in YYYY-MM-DD format. |
product |
`string \ | undefined` |
country |
`string \ | undefined` |
provider |
`string \ | undefined` |
institution_id |
`string \ | undefined` |
Ingestion behavior
POST /internal/analytics/events:- Requires
requireInternalAuth. - Rejects invalid JSON bodies with
INVALID_BODY. - Calls
applyConsentEvent(pool, parsed.data). - Returns
409with{ "status": "dimension_mismatch" }whenapplyConsentEventreports a dimension mismatch.
- Requires
GET /internal/analytics/psu-consent/metrics:- Requires
requireInternalAuth. - Rejects invalid query strings with
INVALID_QUERY. - Validates date ordering so
start_date <= end_date. - Reads four aggregates in parallel:
fetchDailyMetricsfetchFunnelMetricsfetchFailureBreakdownfetchLatencyMetrics
- Requires
POST /internal/analytics/events
{
"title": "Ingest PSU Consent Analytics Event",
"description": "Validates and stores a single PSU consent funnel event for internal analytics",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/internal/analytics/events",
"headers": [
{
"key": "x-internal-token",
"value": "<internal-token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"psu_id\": \"psu_123\",\n \"consent_session_id\": \"sess_123\",\n \"product\": \"product_a\",\n \"country\": \"US\",\n \"provider\": \"provider_a\",\n \"institution_id\": \"inst_123\",\n \"timestamp\": \"2024-01-01T12:00:00.000Z\",\n \"failure_reason\": null,\n \"event_name\": \"consent_start\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Stored by the consent analytics reducer",
"body": "{\n \"status\": \"stored\"\n}"
},
"409": {
"description": "The event dimensions do not match the existing session",
"body": "{\n \"status\": \"dimension_mismatch\"\n}"
}
}
}
GET /internal/analytics/psu-consent/metrics
{
"title": "Get PSU Consent Metrics",
"description": "Returns daily, funnel, failure, and latency metrics for consent analytics",
"method": "GET",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/internal/analytics/psu-consent/metrics",
"headers": [
{
"key": "x-internal-token",
"value": "<internal-token>",
"required": true
}
],
"queryParams": [
{
"key": "start_date",
"value": "2024-01-01",
"required": true
},
{
"key": "end_date",
"value": "2024-01-07",
"required": true
},
{
"key": "product",
"value": "product_a",
"required": false
},
{
"key": "country",
"value": "US",
"required": false
},
{
"key": "provider",
"value": "provider_a",
"required": false
},
{
"key": "institution_id",
"value": "inst_123",
"required": false
}
],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Aggregated consent metrics",
"body": "{\n \"daily\": [],\n \"funnel\": [],\n \"failures\": [],\n \"latency\": []\n}"
}
}
}
Daily PSU Consent Metrics Job
dailyPsuConsentMetrics.ts
[!NOTE] The route returns the direct outputs of
fetchDailyMetrics,fetchFunnelMetrics,fetchFailureBreakdown, andfetchLatencyMetrics. The top-level keys are fixed by the route, while the nested shapes are owned by the analytics service layer.
services/us-api/src/jobs/dailyPsuConsentMetrics.ts
This job refreshes daily aggregates over a lookback window. It can run as a callable function inside tests or as a standalone process when the script is launched directly.
| Method | Description | Returns |
|---|---|---|
resolveLookbackDays |
Reads LOOKBACK_DAYS and falls back to 7 when unset or invalid. |
number |
resolveRunDate |
Reads RUN_DATE, normalizes it to midnight UTC, and rejects invalid dates. |
Date |
runDailyPsuConsentMetricsJob |
Resolves the run parameters and calls refreshDailyMetricsForRange. |
Promise<void> |
Execution behavior
poolOverrideis used when supplied; otherwise the module-levelpoolis used.lookbackDayscan also be provided through theoptionsargument.runDatecan also be provided through theoptionsargument.- When executed directly, the job logs completion or failure and exits the process with
0or1.
PSU Consent Timeout Watchdog
psuConsentTimeoutWatchdog.ts
services/us-api/src/jobs/psuConsentTimeoutWatchdog.ts
This watchdog scans open consent sessions, derives each session deadline from provider-specific or default timeout settings, and emits a synthetic consent_timeout event through the same consent-event pipeline used by normal ingestion.
| Method | Description | Returns |
|---|---|---|
parseProviderTimeoutMap |
Parses PROVIDER_TIMEOUT_MINUTES as JSON and converts values to numbers. |
ProviderTimeoutMap |
resolveDefaultTimeoutMinutes |
Reads DEFAULT_TIMEOUT_MINUTES and falls back to 15 when unset or invalid. |
number |
runPsuConsentTimeoutWatchdog |
Finds sessions without a final status, checks timeout deadlines, and injects consent_timeout events for stale sessions. |
Promise<void> |
Timeout derivation
- The watchdog reads sessions from
analytics.psu_consent_sessionswhere:final_status IS NULLstarted_at IS NOT NULL
- For each row:
- It picks
providerTimeouts[provider]when present. - Otherwise it uses the default timeout.
- It computes
deadline = started_at + timeoutMinutes. - If
deadline > now, the row is skipped. - Otherwise
applyConsentEventis called with:event_name: 'consent_timeout'failure_reason: 'timeout'
- It picks
Watchdog execution
process.argv[1]?.includes('psuConsentTimeoutWatchdog')enables direct execution.- Success and failure are logged to stdout/stderr.
- Errors exit the process with status
1.
Feature Drift and Retraining Jobs
featureDriftJob.ts
services/us-api/src/jobs/featureDriftJob.ts
This job runs the feature-drift detection workflow against the global cashflow feature schema.
| Method | Description | Returns |
|---|---|---|
runDailyFeatureDriftCheck |
Calls runFeatureDriftDetection with the US cashflow feature set and the global schema version. |
Promise<FeatureDriftReport> |
retrainTriggerJob.ts
services/us-api/src/jobs/retrainTriggerJob.ts
This job evaluates whether the latest metrics and drift conditions justify retraining a model artifact.
| Method | Description | Returns |
|---|---|---|
evaluateRetrainingForModel |
Forwards the model artifact ID to evaluateRetrainingTriggers. |
`Promise<RetrainTrigger \ |
modelGovernanceService.ts
services/us-api/src/services/modelGovernanceService.ts
This service holds the drift, schema, retraining, and lineage logic used by the scheduled jobs.
| Method | Description | Returns |
|---|---|---|
ensureFeatureSchemaVersion |
Ensures the global credit feature schema version exists in persistence. | Promise<FeatureSchemaVersion> |
runFeatureDriftDetection |
Compares live evidence snapshots against a baseline distribution and stores a drift report. | Promise<FeatureDriftReport> |
evaluateRetrainingTriggers |
Checks AUC and feature drift thresholds and inserts a pending retrain trigger when needed. | `Promise<RetrainTrigger \ |
recordModelLineage |
Creates model artifact and deployment records when the artifact does not already exist. | Promise<ModelArtifact> |
DriftInput
services/us-api/src/services/modelGovernanceService.ts
| Property | Type | Description |
|---|---|---|
featureSet |
string |
Feature set label used to query evidence snapshots and baselines. |
schemaVersion |
string |
Feature schema version used for drift comparisons. |
sampleLimit |
`number \ | undefined` |
baselineLabel |
`string \ | undefined` |
Drift detection behavior
runFeatureDriftDetectionloads the baseline row by:featureSetschemaVersionbaselineLabelortraining-baseline
- It loads up to
sampleLimit ?? 200evidence snapshots ordered by newest first. - It computes numeric feature distributions and flags features whose z-score magnitude is at least
2. - It writes a new
featureDriftReportrow with:driftScoredriftedFeaturessampleSize
Retraining trigger behavior
evaluateRetrainingTriggerscompares:- the latest AUC snapshot against
aucMin - the latest drift report against
driftScoreMax
- the latest AUC snapshot against
- Default thresholds are:
aucMin: 0.72driftScoreMax: 0.3
- A retrain trigger is created only when at least one reason is present.
- The created trigger is stored with:
status: 'PENDING'reasonas a comma-separated list of trigger reasonsdetails.triggerscontaining structured reason objects
Global Credit Feature Schema
creditFeatureSchema.ts
services/us-api/src/models/creditFeatureSchema.ts
This schema file defines the normalized feature contract used by the drift and retraining pipeline.
| Method | Description | Returns |
|---|---|---|
migrateToGlobalCreditSchemaV1 |
Maps arbitrary feature input onto the global schema and records migration notes. | FeatureMigrationResult |
Constants and types
GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION
global-credit-v1
GlobalCreditFeatureSchemaV1
| Property | Type | Description |
|---|---|---|
schema_version |
typeof GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION |
Normalized schema version. |
income_monthly_avg_usd |
number |
Average monthly income in USD. |
income_stability_index |
number |
Normalized income stability score. |
nsf_overdraft_count_180d |
number |
Count of overdraft events in the last 180 days. |
balance_min_30d_usd |
number |
Minimum balance in the last 30 days. |
rent_payment_detected |
boolean |
Whether rent payment activity was detected. |
debt_payment_ratio_est |
number |
Estimated debt payment ratio. |
FeatureMigrationResult
| Property | Type | Description |
|---|---|---|
schema_version |
typeof GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION |
Schema version assigned to the migrated feature set. |
features |
GlobalCreditFeatureSchemaV1 |
Normalized feature payload. |
migration_notes |
string[] |
Notes about defaulted or unsupported source fields. |
Migration behavior
- Unsupported
feature_setvalues add a migration note. - Missing or non-numeric fields fall back to
defaultFeatureValues. - Every missing field that remains at its default value is logged as a migration note.
- The result is persisted in
evidenceSnapshotby the feature pipeline that calls this schema helper.
Data Contracts Used by Consent and Analytics
types.ts
services/us-api/src/models/types.ts
PurposeValues
RENTAL_SCREENING, LENDING_UNDERWRITING, ACCOUNT_OPENING, INCOME_VERIFICATION, FRAUD_PREVENTION, GENERAL_PERSONAL_FINANCE
DataCategoryValues
IDENTITY_BASIC, ACCOUNTS, BALANCES, TRANSACTIONS, INCOME, EMPLOYMENT, CASHFLOW_FEATURES, DEVICE_RISK, WATCHLIST_SCREENING
ConnectionStatusValues
ACTIVE, REAUTH_REQUIRED, DEGRADED, DISCONNECTED
These value sets define the consent and connection states used across token issuance, access checks, and related workflows.
Feature Flows
Consent Event Ingestion Flow
sequenceDiagram
participant Client as Internal Client
participant Route as registerInternalAnalyticsRoutes
participant Auth as requireInternalAuth
participant Parser as zod Schema
participant Analytics as applyConsentEvent
participant DB as Postgres Pool
Client->>Route: POST /internal/analytics/events
Route->>Auth: preHandler
Auth-->>Route: accepted when x-internal-token matches
Route->>Parser: validate body
Parser-->>Route: parsed event
Route->>Analytics: applyConsentEvent(pool, data)
Analytics->>DB: write session and event rows
DB-->>Analytics: persisted result
Analytics-->>Route: status
Route-->>Client: 200 or 409
The same event pipeline is reused by the timeout watchdog, which means synthetic timeout events flow through the same reducer as real event ingestion.
Timeout Derivation Flow
sequenceDiagram
participant Scheduler as Scheduler
participant Job as runPsuConsentTimeoutWatchdog
participant DB as Postgres Pool
participant Analytics as applyConsentEvent
Scheduler->>Job: execute watchdog
Job->>DB: query open sessions
DB-->>Job: rows with final_status null
loop each stale session
Job->>Job: derive deadline from started_at and provider timeout
Job->>Analytics: applyConsentEvent with consent_timeout
Analytics->>DB: update analytics session and event tables
DB-->>Analytics: persisted timeout state
end
Job-->>Scheduler: complete
Signed Webhook Delivery Flow
sequenceDiagram
participant Consent as createConsent or revokeConsent or exchangeToken
participant Webhook as dispatchWebhook
participant DB as Prisma
participant Partner as Partner Endpoint
Consent->>Webhook: dispatchWebhook(partnerId, event)
Webhook->>DB: findMany active endpoints
DB-->>Webhook: webhookEndpoint rows
loop each endpoint
Webhook->>DB: create webhookDelivery PENDING
Webhook->>Webhook: signPayload(secret, payload)
Webhook->>Partner: POST event body with X-Webhook-Signature
Partner-->>Webhook: HTTP response
Webhook->>DB: update delivery DELIVERED or FAILED
end
Webhook-->>Consent: resolve or throw ApiError 502
Drift and Retraining Flow
sequenceDiagram
participant Scheduler as Scheduler
participant DriftJob as runDailyFeatureDriftCheck
participant Gov as runFeatureDriftDetection
participant RetrainJob as evaluateRetrainingForModel
participant Trigger as evaluateRetrainingTriggers
participant DB as Prisma
Scheduler->>DriftJob: run daily drift job
DriftJob->>Gov: runFeatureDriftDetection
Gov->>DB: load baseline and evidence snapshots
DB-->>Gov: baseline and samples
Gov->>DB: create featureDriftReport
DB-->>Gov: report persisted
Scheduler->>RetrainJob: evaluate retraining
RetrainJob->>Trigger: evaluateRetrainingTriggers
Trigger->>DB: read modelPerformanceSnapshot and featureDriftReport
DB-->>Trigger: latest records
Trigger->>DB: create retrainTrigger when needed
DB-->>Trigger: trigger persisted or null
State Management
Consent state
The consent lifecycle uses explicit status values in persistence and in receipt output:
PENDING_USER_ACTIONACTIVEREVOKED
ensureConsentActive rejects both revoked and expired consents with CONSENT_REVOKED.
Token and refresh state
Refresh behavior is controlled by consent fields:
refreshEnabledmaxRefreshPerDayrefreshEventrows for daily counting
refreshToken only issues a new token pair after validating the stored refresh token hash and enforcing the per-day refresh limit.
Analytics session state
The consent analytics tables carry funnel state through session rows and event rows. The timeout watchdog only targets rows where final_status is still null, then drives those sessions to a terminal timeout event through applyConsentEvent.
Webhook delivery state
Webhook deliveries move through:
PENDINGDELIVEREDFAILED
The database row is created before the HTTP call and updated after the call or on exception.
Retraining state
Retrain triggers are created as:
PENDING
The trigger stores structured reasons in details.triggers, and the reason column concatenates the trigger reasons into a single string.
Integration Points
- PostgreSQL and Prisma: all consent logs, webhook deliveries, analytics sessions, metrics, drift reports, and retraining triggers persist through Prisma or direct
pgqueries. - Internal auth: the analytics API requires
requireInternalAuth. - Partner webhook receivers:
dispatchWebhookposts signed callbacks to partner-supplied endpoint URLs. - Model governance: consent-derived evidence snapshots feed
runFeatureDriftDetectionandevaluateRetrainingTriggers. - Environment variables:
LOOKBACK_DAYSRUN_DATEPROVIDER_TIMEOUT_MINUTESDEFAULT_TIMEOUT_MINUTESinternalApiTokenvia app configjwtPublicKeyandjwtPrivateKeythrough config-backed token flows
Error Handling
The domain uses ApiError for predictable control-flow failures and plain Error for job-level preconditions.
requireInternalAuth403 FORBIDDENwhen the internal token is missing or mismatched
internalAnalytics.ts400 INVALID_BODYfor invalid event payloads400 INVALID_QUERYfor invalid or reversed date ranges409withdimension_mismatchwhen analytics dimensions do not align
dispatchWebhook502 PROVIDER_UNAVAILABLEwhen delivery fails
getConsentReceipt404 NOT_FOUNDfor missing consent
ensureConsentActive409 CONSENT_REVOKEDfor revoked or expired consent
refreshToken403 LEGAL_RESTRICTIONfor invalid refresh token409 CONSENT_REVOKEDfor inactive or expired consent429 REFRESH_LIMIT_EXCEEDEDwhen refresh policy is exhausted
resolveRunDate- throws
RUN_DATE must be YYYY-MM-DDfor invalid values
- throws
runFeatureDriftDetection- throws when the baseline or evidence snapshots are missing
Caching Strategy
This section is driven by durable writes and direct reads from PostgreSQL and Prisma-backed tables. The code here does not introduce a cache layer for receipts, webhook delivery state, analytics aggregation, or drift/retraining decisions.
The only replay-sensitive state visible in this section is the refresh-token lookup and token revocation check, both of which read persisted hashes and current rows at request time.
Dependencies
pgfor direct analytics queries and job execution@prisma/clientthroughprismafor consent, token, webhook, and governance recordsjsonwebtokenfor RS256 token issuance and verificationcryptofor consent IDs, token IDs, delivery IDs, and HMAC signatureszodfor internal analytics request validationfetchfor outbound webhook delivery and callback postingpg-memandjestinservices/us-api/test/psuConsentAnalytics.test.ts
Testing Considerations
psuConsentAnalytics.test.ts
services/us-api/test/psuConsentAnalytics.test.ts
This test file exercises the consent analytics reducer and watchdog behavior against an in-memory Postgres instance loaded from the migration SQL.
| Scenario | What it verifies |
|---|---|
idempotency: duplicate event does not update twice |
The same analytics event is not double-counted and the session start timestamp remains stable. |
first terminal wins even if another terminal arrives later |
The first terminal event controls the session’s final status. |
step timestamps are first-write-wins via COALESCE |
Existing session timestamps are preserved when later events arrive. |
daily metrics aggregation counts sessions by started_at date |
Daily metric rollups count sessions by session start date. |
timeout watchdog emits consent_timeout for stale sessions |
The watchdog drives stale sessions into a timeout state using the configured default timeout window. |
Test setup pattern
createTestPool()loads001_create_psu_consent_analytics.sqlintopg-mem.jest.useFakeTimers().setSystemTime(...)freezes time for timeout derivation.- The tests call:
applyConsentEventrefreshDailyMetricsForRangerunPsuConsentTimeoutWatchdog
Key Classes Reference
| Class | Location | Responsibility |
|---|---|---|
consentService.ts |
consentService.ts |
Consent creation, revocation, receipt generation, and active-consent checks |
tokenService.ts |
tokenService.ts |
Token exchange, refresh, introspection, and consent activation webhooks |
webhookService.ts |
webhookService.ts |
Signed webhook delivery and persisted delivery tracking |
internalAnalytics.ts |
internalAnalytics.ts |
Internal consent analytics ingestion and metrics endpoints |
dailyPsuConsentMetrics.ts |
dailyPsuConsentMetrics.ts |
Scheduled daily metrics refresh job |
psuConsentTimeoutWatchdog.ts |
psuConsentTimeoutWatchdog.ts |
Stale-session timeout watchdog |
featureDriftJob.ts |
featureDriftJob.ts |
Daily drift job entry point |
retrainTriggerJob.ts |
retrainTriggerJob.ts |
Retraining trigger job entry point |
modelGovernanceService.ts |
modelGovernanceService.ts |
Feature schema, drift, retraining, and model lineage governance |
psuConsentAnalytics.test.ts |
psuConsentAnalytics.test.ts |
Analytics reducer and watchdog verification |