feat(realtime): Broadcast facade, firebase-database/polling/memory transports and device push

[3m1n3nc3]

Summary

Extends @arkstack/notifications and @arkstack/realtime so apps can run all their realtime on Arkstack, not only per-user notifications.

Added

• Broadcast facade (@arkstack/notifications)
  • Channel authorization registry: Broadcast.channel('private-team.{teamId}', (user, params) => ...). Placeholders match one dot-free segment, the first matching rule decides, and unmatched channels are denied. The per-user channel stays allowed for its own user.
  • broadcast() for arbitrary events, handleAuth() for custom auth routes (e.g. guest tokens), clientConfig(), and routes() registering POST /realtime/auth and GET /realtime/config.
• New transports, on both server and client:
  • firebase-database: Realtime Database channels. Per-user grants expire after a TTL and are checked by security rules; prune() deletes old events in bounded batches.
  • polling: signal-only. Clients refetch through RealtimeClient.onPoll().
  • memory: for tests. Shared on globalThis so it works across module graphs.
• Device push separate from streaming
  • Set drivers.realtime.push: 'firebase'. Tokens come from a push_tokens resolver or user.pushTokens.
  • Per send: .push(false) skips the push, .devices(tokens) targets specific devices, and the multicast outcome is on result.push.
  • Client gets deviceToken().
• Self-hosted Pusher-protocol servers (soketi): transports.pusher.host/port on the server, wsHost/wsPort on the client.

Fixed

• UserNotificationCenter.send() and Notification.db().broadcast() broadcast on the user's channel. Before, they used push tokens as channel names, so users without tokens got nothing.
• Notification.db().broadcast() now returns the builder, so the documented chain works.
• The Pusher auth route from registerAuthRoute():
  • returns HTTP 200, since pusher-js rejects anything else;
  • registers H3 on @arkstack/driver-h3;
  • authorizes through the registry.

Compatibility

• When drivers.realtime.push is unset and the transport is firebase, notifications still reach users' devices.
• Breaking: an unknown transport name now throws when the notification is constructed. Before, it fell back to Pusher.
• PUSHER_HOST / PUSHER_PORT are now read from env.
• RealtimeDriverName and RealtimeTransportName gain members, so exhaustive switches over them need new cases.

Docs

• Notifications guide: transports, channel authorization, device push, Realtime Database rules and pruning, polling, testing.
• Scaffold templates and the changelog are updated.

Test plan

• vitest run: 73 files, all passing.
• tsc --noEmit and eslint clean for both packages; both packages build.
• Express template notifications config typechecks against the new types.
• Live check against a real soketi server.
• Live check against Firebase: Realtime Database rules and FCM deviceToken().

[codecov]

Codecov Report

❌ Patch coverage is 68.95674% with 122 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/notifications/src/Broadcast.ts	56.60%	45 Missing and 1 partial ⚠️
...otifications/src/drivers/realtime/firebaseAdmin.ts	3.70%	26 Missing ⚠️
...tions/src/drivers/realtime/PusherRealtimeDriver.ts	37.93%	18 Missing ⚠️
...drivers/realtime/FirebaseDatabaseRealtimeDriver.ts	85.71%	8 Missing ⚠️
...kages/realtime/src/transports/firebase-database.ts	88.46%	6 Missing ⚠️
packages/realtime/src/transports/memory.ts	80.76%	5 Missing ⚠️
...ions/src/drivers/realtime/PollingRealtimeDriver.ts	42.85%	4 Missing ⚠️
packages/realtime/src/RealtimeClient.ts	90.62%	3 Missing ⚠️
...ckages/notifications/src/UserNotificationCenter.ts	60.00%	2 Missing ⚠️
...tions/src/drivers/realtime/MemoryRealtimeDriver.ts	86.66%	2 Missing ⚠️
... and 2 more

📢 Thoughts on this report? Let us know!