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

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.

The lifecycle methods create the durable audit records that underpin receipts:

  • createConsent writes a consentLog row with action: 'CREATED'.
  • revokeConsent writes a consentLog row with action: 'REVOKED'.
  • exchangeToken writes a consentLog row with action: '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] signPayload signs event.payload, while dispatchWebhook sends { event, data: event.payload }. The code does not sign the outer envelope, so webhook verification must target the inner payload format used by signPayload.

  • Delivery IDs are generated as whd_<hex>.
  • The same delivery ID is used as the database primary key and as the Idempotency-Key header.
  • Headers sent to the partner are:
    • Content-Type: application/json
    • X-Webhook-Signature
    • Idempotency-Key
  • Delivery status is updated after the HTTP response:
    • DELIVERED when response.ok is true
    • FAILED otherwise

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 409 with { "status": "dimension_mismatch" } when applyConsentEvent reports a dimension mismatch.
  • 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:
      • fetchDailyMetrics
      • fetchFunnelMetrics
      • fetchFailureBreakdown
      • fetchLatencyMetrics

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}"
        }
    }
}

dailyPsuConsentMetrics.ts

[!NOTE] The route returns the direct outputs of fetchDailyMetrics, fetchFunnelMetrics, fetchFailureBreakdown, and fetchLatencyMetrics. 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

  • poolOverride is used when supplied; otherwise the module-level pool is used.
  • lookbackDays can also be provided through the options argument.
  • runDate can also be provided through the options argument.
  • When executed directly, the job logs completion or failure and exits the process with 0 or 1.

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_sessions where:
    • final_status IS NULL
    • started_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 applyConsentEvent is called with:
      • event_name: 'consent_timeout'
      • failure_reason: 'timeout'

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

  • runFeatureDriftDetection loads the baseline row by:
    • featureSet
    • schemaVersion
    • baselineLabel or training-baseline
  • It loads up to sampleLimit ?? 200 evidence 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 featureDriftReport row with:
    • driftScore
    • driftedFeatures
    • sampleSize

Retraining trigger behavior

  • evaluateRetrainingTriggers compares:
    • the latest AUC snapshot against aucMin
    • the latest drift report against driftScoreMax
  • Default thresholds are:
    • aucMin: 0.72
    • driftScoreMax: 0.3
  • A retrain trigger is created only when at least one reason is present.
  • The created trigger is stored with:
    • status: 'PENDING'
    • reason as a comma-separated list of trigger reasons
    • details.triggers containing 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_set values 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 evidenceSnapshot by the feature pipeline that calls this schema helper.

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

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

The consent lifecycle uses explicit status values in persistence and in receipt output:

  • PENDING_USER_ACTION
  • ACTIVE
  • REVOKED

ensureConsentActive rejects both revoked and expired consents with CONSENT_REVOKED.

Token and refresh state

Refresh behavior is controlled by consent fields:

  • refreshEnabled
  • maxRefreshPerDay
  • refreshEvent rows 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:

  • PENDING
  • DELIVERED
  • FAILED

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 pg queries.
  • Internal auth: the analytics API requires requireInternalAuth.
  • Partner webhook receivers: dispatchWebhook posts signed callbacks to partner-supplied endpoint URLs.
  • Model governance: consent-derived evidence snapshots feed runFeatureDriftDetection and evaluateRetrainingTriggers.
  • Environment variables:
    • LOOKBACK_DAYS
    • RUN_DATE
    • PROVIDER_TIMEOUT_MINUTES
    • DEFAULT_TIMEOUT_MINUTES
    • internalApiToken via app config
    • jwtPublicKey and jwtPrivateKey through config-backed token flows

Error Handling

The domain uses ApiError for predictable control-flow failures and plain Error for job-level preconditions.

  • requireInternalAuth
    • 403 FORBIDDEN when the internal token is missing or mismatched
  • internalAnalytics.ts
    • 400 INVALID_BODY for invalid event payloads
    • 400 INVALID_QUERY for invalid or reversed date ranges
    • 409 with dimension_mismatch when analytics dimensions do not align
  • dispatchWebhook
    • 502 PROVIDER_UNAVAILABLE when delivery fails
  • getConsentReceipt
    • 404 NOT_FOUND for missing consent
  • ensureConsentActive
    • 409 CONSENT_REVOKED for revoked or expired consent
  • refreshToken
    • 403 LEGAL_RESTRICTION for invalid refresh token
    • 409 CONSENT_REVOKED for inactive or expired consent
    • 429 REFRESH_LIMIT_EXCEEDED when refresh policy is exhausted
  • resolveRunDate
    • throws RUN_DATE must be YYYY-MM-DD for invalid values
  • 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

  • pg for direct analytics queries and job execution
  • @prisma/client through prisma for consent, token, webhook, and governance records
  • jsonwebtoken for RS256 token issuance and verification
  • crypto for consent IDs, token IDs, delivery IDs, and HMAC signatures
  • zod for internal analytics request validation
  • fetch for outbound webhook delivery and callback posting
  • pg-mem and jest in services/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() loads 001_create_psu_consent_analytics.sql into pg-mem.
  • jest.useFakeTimers().setSystemTime(...) freezes time for timeout derivation.
  • The tests call:
    • applyConsentEvent
    • refreshDailyMetricsForRange
    • runPsuConsentTimeoutWatchdog

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