feat(alertRules): country-scoping — schema + mutation + relay filter + UI picker

[koala73]

Summary

Adds an optional countries field to alertRules so users can scope notifications to specific countries (e.g. only alert me about events in Iran or Saudi Arabia). Empty/absent → all countries (today's behavior; backward-compatible).

Independent PR — not stacked on the followed-countries primitive (#3621/#3629/#3631). Branches directly off main. Smart-defaults the country picker UI from PR A's getFollowed() helper IF available at runtime via a window-registry pattern (no static or dynamic import), but ships fully functional without PR A.

What ships

5 layers:

1. Convex schema (convex/schema.ts) — countries: v.optional(v.array(v.string())) on alertRules. No migration; existing rows treated as "all countries".

2. Convex mutations (convex/alertRules.ts) — setAlertRules, setAlertRulesForUser, setNotificationConfigForUser accept countries arg via shared normalizeCountries(). Trim/uppercase/regex (^[A-Z]{2}$)/dedupe. Cap-50 anti-abuse ceiling → ConvexError({kind: 'COUNTRIES_LIMIT_EXCEEDED'}). Preserve-on-omit; explicit [] resets to "all". Shape-only validation (NOT ISO-3166 registry) — keeps independent of PR A's convex/lib/iso2.ts.

3. HTTP / API forwarding (convex/http.ts, api/notification-channels.ts, src/services/notification-channels.ts) — countries flows through the full HTTP → API → mutation chain.

4. Relay filter (scripts/notification-relay.cjs) — new eventMatchesCountryScope(event, rule) helper in the per-rule eligibility filter. Country attribution priority: event.payload.countryCode → event.payload.country → event.country (publishers are inconsistent; precedent set by regional-snapshot, ais-relay, rss_alert). PERMISSIVE semantics for unattributed events: events with no country attribution (or malformed values like 'USA' / 'United States') ARE delivered to country-scoped rules. Strict semantics still apply when the event IS attributed but doesn't match. Documented inline.

   Why permissive on unattributed? Most current publishers don't emit a country code. Strict drop-on-missing would mean a user setting countries=['US'] gets ZERO alerts — strictly worse UX than "occasional unscoped global event slips through." A user opting into country-scope expects to receive AT LEAST events from those countries; permissive delivery on unattributed events meets that expectation. As publishers add country attribution (planned follow-up audit), scoped delivery tightens automatically. A future strict-mode opt-in (e.g. rule.countriesStrict=true) is left to a follow-up UI surface.

5. UI picker (src/utils/country-chip-picker.ts + src/services/notifications-settings.ts) — multi-select chip picker with curated 20-country short-list + type-to-add 2-letter input for the long tail. Smart-default seed via loadFollowedCountriesSafe() — synchronous read from window.__wmFollowedCountries?.getFollowed(). PR A's followed-countries module (when it ships) self-registers on window.__wmFollowedCountries; this picker reads if-present, returns [] if absent. Smart-default ONLY applies on NEW-rule create; editing existing rules respects stored countries. Centralized save state via getCurrentAlertRuleFormState() so every alertRules save path threads countries through.

Test plan

• npm run typecheck — clean
• npm run typecheck:api — clean
• npm run test:convex — 225 pass
• npm run test:data — 8312 pass (+ ~52 new across the three layers)
• vite build — succeeds (verified the window-registry approach has no Vite alias coupling)

New tests (highlights):

• 8 convex mutation tests: shape validation, normalization (lowercase, whitespace, dedupe), preserve-on-omit, explicit-reset-to-empty, cap-50, backward compat.
• 18 relay filter tests: empty/all, US/GB match, no-attribution-permissive-deliver, empty-string-permissive, whitespace-permissive, payload field priority, lowercase normalization, malformed-country-permissive, attributed-mismatch-strict-drop.
• 26 picker tests: render shape, smart-default new vs edit, preselectCountry precedence, loadFollowedCountriesSafe window-registry behavior (absent / present / throws / non-array / missing-method), save-path centralization assertions (every saveAlertRules call site spreads ...state), normalizeIso2, type-to-add, dedup, cap.

Key design decisions

• Permissive-on-unattributed relay semantics — when a rule sets countries = ['US'], an event with no country attribution IS delivered. Strict semantics still apply when the event IS attributed but doesn't match. Errs on over-delivery (occasional global event slips through) over under-delivery (zero-alert silent failure).
• Centralized save state via getCurrentAlertRuleFormState() — every alertRules save path (picker debounce, channel connect, enable toggle, sensitivity, AI digest toggle) sources its full payload from one helper. Catches future drift: any new save path that hand-rolls its own payload is flagged by the source-grep test.
• Window-registry smart-default — loadFollowedCountriesSafe() reads from window.__wmFollowedCountries?.getFollowed(). PR A self-registers in its own module-init block when it eventually merges; PR feat(alertRules): country-scoping — schema + mutation + relay filter + UI picker #3632 reads-if-present. No Vite alias coupling, no @vite-ignore tricks, no dynamic import that breaks in production browser builds.
• Shape validation, not registry validation — 'XX' passes the regex but no event will match it; keeps this PR independent of PR A's canonical alpha-2 list.
• Cap at 50 — defensive ceiling against patched-client abuse (~250 ISO countries; nobody legitimately wants 100+).
• Three mutations updated, not just setAlertRules — setAlertRulesForUser (HTTP path) and setNotificationConfigForUser (atomic delivery-mode flow) also accept the field; without those, the countries arg would only persist via the direct-mutation path.

Unlocks

• PR B's U8 R9 pre-fill (feat(followed-countries): consumer wiring PR B — CII pin + filter chip + deep-dive notify #3629). The "Notify me about this country" sub-action on the deep-dive can now pass the viewed country to the notifications create form and have it pre-checked. Three TODO injection points are already marked in PR B's src/utils/notify-country-link.ts — wire-swap once both PRs land.
• Per-country digest emails (future PR). Once notifications are country-scoped, per-country digest aggregation becomes a natural follow-up.
• PR A integration — when PR A merges, a tiny follow-up adds if (typeof window !== 'undefined') { (window as any).__wmFollowedCountries = { getFollowed }; } to PR A's followed-countries module. This PR's smart-default activates automatically.

Out of scope

• Digest cron country filter. This PR only filters the realtime fan-out path. The digest aggregation runs from a separate per-user cache; country-scoping there is a future PR.
• countFollowers rate limit (still open from PR A). Vercel edge wrapper.
• Strict-mode opt-in for country-scoped rules. Today's relay is permissive on unattributed events. A future UI surface (rule.countriesStrict=true) can opt users into strict drop-on-missing once publisher attribution coverage is high enough.
• alertRules schema deploy ordering safety net (memory: convex-schema-deployment-mismatch). Convex auto-deploys on merge; the schema field is optional so handlers deploy in the same push without race risk.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
worldmonitor	Ready	Preview, Comment	May 9, 2026 9:21am

[greptile-apps]

Greptile Summary

This PR adds optional country-scoping to alertRules so users can restrict realtime notifications to specific countries. It touches all five layers — Convex schema, three mutations, the HTTP/API forwarding chain, the notification relay filter, and a new UI chip picker.

• Schema + mutations: countries: v.optional(v.array(v.string())) added to the alertRules table; a shared normalizeCountries() helper applies trim/uppercase/regex/dedupe/cap-50 consistently across all three updated mutations with correct preserve-on-omit semantics.
• Relay filter: New eventMatchesCountryScope() function with well-documented strict-no-attribution semantics and correct payload.countryCode → payload.country → event.country extraction priority, wired into the per-rule realtime matching loop.
• UI picker: Self-contained mountCountryChipPicker with a 20-country short-list, type-to-add input, and a graceful-degradation dynamic import for the optional getFollowed() smart-default.

Confidence Score: 3/5

Safe to merge after fixing the missing abort-signal guard in the picker mount path; all other layers are solid.

The abort-signal gap in notifications-settings.ts is a real functional defect on the new-rule path: when loadFollowedCountriesSafe resolves after the settings panel has been closed, a stale countryPicker handle is written back to the outer scope and the debounced onChange can fire a ghost mutation for a rule the user no longer sees. The relay filter and Convex mutation logic are otherwise well-implemented with thorough tests.

src/services/notifications-settings.ts — the async picker-mount block needs a post-await abort check. convex/http.ts — minor validation gap in the set-notification-config path.

Important Files Changed

Filename	Overview
convex/alertRules.ts	Adds countries arg to three mutations via a shared normalizeCountries() helper; normalization (trim, uppercase, regex, dedupe, cap-50) and preserve-on-omit semantics are correctly implemented.
scripts/notification-relay.cjs	Adds eventMatchesCountryScope helper with correct strict-no-attribution semantics and multi-field extraction priority; properly wired into the per-rule realtime matching filter.
src/services/notifications-settings.ts	Mounts the country chip picker on reload; missing signal.aborted guard after await loadFollowedCountriesSafe() can leave a stale countryPicker handle attached to orphaned DOM, risking a ghost mutation on the debounced save path.
src/utils/country-chip-picker.ts	New self-contained chip picker with correct normalizeIso2 mirroring the server regex, safe dynamic-import degradation via /* @vite-ignore */, and proper destroy/cleanup logic.
convex/http.ts	Passes countries through both HTTP action handlers; set-alert-rules correctly validates with a 400, but set-notification-config silently drops a non-array value instead of rejecting it.
convex/schema.ts	Adds countries: v.optional(v.array(v.string())) to alertRules; backward-compatible since absent field means all-countries.
api/notification-channels.ts	Threads countries through the Vercel Edge handler for both set-alert-rules and set-notification-config actions with no functional issues.
src/services/notification-channels.ts	Adds countries?: string[] to AlertRule interface and setNotificationConfig args; straightforward type extension with no issues.

Sequence Diagram

sequenceDiagram
    participant UI as Country Chip Picker
    participant NS as notifications-settings.ts
    participant API as api/notification-channels.ts
    participant HTTP as convex/http.ts
    participant MUT as alertRules mutation
    participant DB as Convex DB (alertRules)
    participant RELAY as notification-relay.cjs

    UI->>NS: onChange (debounced 800ms)
    NS->>NS: saveCurrentAlertRule() reads DOM + picker.getValue()
    NS->>API: "POST /api/notification-channels {action, countries:[...]}"
    API->>HTTP: "convexRelay({countries})"
    HTTP->>HTTP: validate Array.isArray(countries)
    HTTP->>MUT: "setAlertRulesForUser({countries})"
    MUT->>MUT: normalizeCountries() trim/upper/regex/dedupe/cap-50
    MUT->>DB: "patch({countries:[...]})"

    Note over RELAY: On incoming event
    RELAY->>RELAY: eventMatchesCountryScope(event, rule)
    RELAY->>RELAY: extract countryCode to country to event.country
    RELAY->>RELAY: normalize + regex check
    RELAY->>RELAY: rule.countries.includes(normalized)
    RELAY-->>RELAY: deliver or drop

Loading

Comments Outside Diff (1)

1. convex/http.ts, line 597-600 (link)

   Inconsistent countries validation between the two action handlers

   set-alert-rules explicitly rejects a non-array countries with a 400, but set-notification-config silently coerces a non-array value to undefined. A caller that passes countries: "US" to set-notification-config will receive a 200 even though the field was silently dropped. Adding the same guard keeps the two paths consistent.

_{Reviews (1): Last reviewed commit: "feat(alertRules): country-scoping for al..." | Re-trigger Greptile}

[greptile-apps]

Missing abort-signal check after async gap

loadFollowedCountriesSafe() may call into the getFollowed service, which can take hundreds of milliseconds. If the user closes the settings panel during that window, signal is aborted and the component tears down — but there is no if (signal.aborted) return; guard between the await and the mountCountryChipPicker call. The result is: countryPicker is assigned a live handle pointing at an orphaned DOM element, the onChange debounce arm still fires 800 ms later, and saveCurrentAlertRule calls countryPicker.getValue() on that orphaned picker — sending a ghost mutation to Convex for a rule the user may have already edited or deleted.