@hyperse-hub/hps-plugin-risk-control
Vendure plugin that persists and queries risk signals (RiskSignal) through the Admin API. Each row is an auditable fact or decision—e.g. address clustering anomalies, same email across accounts, high cancellations/refunds, manual review—so rules, operations tooling, and LLM-based risk workflows can share one source of truth.
Features
- Signal-oriented model: Multiple rows per email or customer; keeps a timeline and evidence.
- Category and source:
RiskSignalCategory / RiskSignalSource (GraphQL enums align with the database).
- Structured + narrative:
evidence (JSON for rules/dashboards), llmContext (JSON for prompts).
- Relations: Optional
Customer and Order; emailNormalized joins mailboxes across accounts.
- Admin GraphQL: Paginated list, get-by-id, and a union context query (
riskSignalsForContext) over customer / email / order.
- Dashboard menu: Registers a Hyperse Admin entry at
/risk-control (UI lives under ui/ in this package).
Installation
Register the plugin in your Vendure config:
The risk_signal table is created when the schema is synchronized the first time.
Data model (high level)
| Field (subset) | Description |
|---|
emailNormalized / emailDisplay | Normalized mailbox and optional original casing for display |
addressText / addressFingerprint | Raw address and a stable fingerprint from your pipeline (hash, geohash, etc.) |
category / source | Why the signal exists and how it was produced |
riskScore | 0–100; semantics are defined by your integration |
reasonSummary / detail | Short label and longer explanation |
evidence / llmContext | Arbitrary JSON payloads |
customerId / |
On create, the server requires at least one anchor: email, customerId, orderId, or addressFingerprint.
Admin GraphQL (summary)
Field-level descriptions live in src/api/common/risk.type.ts and src/api/admin-api/risk.api.ts.
| Operation | Description |
|---|
riskSignal(id) | Fetch one signal |
riskSignals(options) | Paginated list (RiskSignalListOptions: filters/sort generated for the entity) |
riskSignalsForContext(input) | Union over customerId or email or orderId; ordered by createdAt desc; take defaults to 100, max 500 |
createRiskSignal / updateRiskSignal / deleteRiskSignal | Mutations; delete is a hard delete—pair with retention policy and tight roles in production |
Permissions
Defaults: ReadCustomer for reads, UpdateCustomer for writes. Swap in custom permissions or gateway rules if you need separation from general CS roles.
LLM / rules integration
- Write: On rule hits, call
createRiskSignal; put countable facts in evidence (e.g. refunds in a window, linked account ids) and a short narrative or bullet object in llmContext.
- Read: Before checkout or in agent UIs, call
riskSignalsForContext and feed detail, evidence, and llmContext (within the capped list) into your prompt.
- Idempotency: Use
externalRef; add a DB unique constraint if needed (e.g. on (source, externalRef)).
Development
Package exports
The public entry exports include HpsPluginRiskControl, RiskSignal, RiskSignalCategory, RiskSignalSource, RiskSignalService, and normalizeEmail for use from other plugins or jobs.
License
MIT (see repository LICENSE).