feat(admin): userNotificationSend — push notification to a single user

[bobodread876]

Why

Support needs to reach a specific user in the app — e.g. ask a user on an old build to update, or tell them their top-up was resolved. The existing admin sendNotification mutation is FCM topic broadcast only; the per-user plumbing (PushNotificationsService().sendNotification({ deviceTokens, ... })) existed but was only wired for cashout notifications.

What

New admin mutation:

mutation {
  userNotificationSend(input: {
    username: "jaceth2009"        # or accountId: "<uuid>" — exactly one required
    title: "Please update Flash"
    body: "A new version fixes the issue you reported."
  }) {
    errors { message code }
    success
  }
}

• src/app/admin/send-user-notification.ts — account → kratos user → device tokens → push (mirrors sendCashoutNotification, but awaits the service result properly)
• src/graphql/admin/root/mutation/user-notification-send.ts — exactly-one-of accountId/username validation, trim + length caps (title 256, body 1024), and a clear operator-facing error when the user has no registered device tokens
• Registered as userNotificationSend in the admin schema; SDL regenerated via yarn write-sdl

Tests

• test/flash/unit/app/admin/send-user-notification.spec.ts — happy path, kratos lookup, account/user/push-service error propagation
• test/flash/unit/graphql/admin/user-notification-send.spec.ts — resolver-level: input validation (both/neither identifier, empty/oversize title+body, malformed accountId/username), by-accountId and by-username sends, trim behavior, username-not-found, no-device-tokens, push-failure mapping

yarn test:unit (196 suites, 1943 tests) green; yarn tsc-check and eslint clean.

Follow-up

ERPNext admin panel (frappe-flash-admin) gets a "specific user" target on the alert-users page that calls this mutation — separate PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_016MsAGwtS4sNodzWu2VMTKR

Review follow-up — observed delivery, not inferred (72ef392)

The first cut inferred success from result.tokens.length < user.deviceTokens.length — "was at least one token NOT reported stale?", which is not "did any device receive it?". A user whose only iOS device has an expired APNs auth key gets messaging/third-party-auth-error, invalidTokens stays empty, the service returned bare true, and the operator saw success: true with nothing delivered. Same fail-open shape as the phantom "conversion successful" in #483.

• push-notifications.ts now returns a NotificationsServiceError when Firebase is not initialised (was a FIXME'd return true) and when the batch came back with successCount === 0.
• DeviceTokensNotRegisteredNotificationsServiceError carries the real successCount; sendUserNotification keys success off it.
• New AllDeviceTokensStaleNotificationsServiceError separates "every token was stale and has just been pruned" from "user never had a device token" — the operator message for the first case now says the tokens were cleared and to ask the user to reopen the app, rather than sending them chasing "they never logged in".
• The stale-token prune result is no longer discarded — a failed mongo write logs a warning instead of silently leaving dead tokens for every retry to re-send to.
• username is trimmed before lookup (UsernameRegex rejects surrounding whitespace, so a value pasted out of a support ticket read as "Invalid username").

Caller safety for the new error branches: every existing push caller either reads .tokens off the stale-token error or logs-and-continues on any NotificationsServiceError — send-lightning, on-receive, update-pending-invoices, settle-payout-txn, add-settled-on-chain-transaction, add-pending-on-chain-transaction, send-default-wallet-balance-to-users, and the bridge/referral best-effort wrappers (all Promise<void>). No payment or deposit path aborts because a push failed. The sibling cashoutNotificationSend mutation now correctly reports failure where it previously reported a phantom success.

New/extended tests: test/flash/unit/services/notifications/push-notifications.spec.ts (both fail-open cases + successCount plumbing); app spec covers successCount 0 vs >0 and the prune-failure warning; the resolver spec now asserts which error message comes back (username-not-found vs invalid, firebase-down, all-stale vs no-tokens) instead of only counting errors, plus username trimming. Full unit suite: 197 suites / 1955 tests green.

[linear]

ENG-551