@kumiai/hub-wake

Wake-notification storage and delivery for a kumiai hub: a push doorbell that tells a suspended device to reconnect.

Server-side, optional. See wake notifications for why the package exists and what it deliberately does not do.

Surface

• createMemoryWakeRegistry() — an in-memory WakeRegistry. Reference implementation and test double; a production host wants a durable one, checked against testWakeRegistryConformance from @kumiai/hub-conformance.
• createWebPushSender({ vapid, ttl?, jwtLifetime?, allowEndpoint?, runtime? }) — a WakeSender for any endpoint speaking RFC 8030 Web Push: browser push services, UnifiedPush distributors, ntfy, or a self-hosted relay. POSTs the sealed body untouched, with a VAPID (RFC 8292) Authorization header it signs itself. allowEndpoint defaults to https: only: an endpoint is an opaque string the hub never parses, so without it an authenticated DID could aim the hub at an internal host. That default is a scheme floor, not an origin defense — an HTTPS endpoint on an internal host (a loopback admin port, a metadata service) still passes it and still lets a caller read back a 404/410-vs-anything-else outcome through unregisterWake(). A host on a network with internal HTTPS services should narrow allowEndpoint to an allowlist of origins; widen it instead only for a self-hosted relay on plain HTTP. A rejected endpoint resolves to retry, never gone — a policy refusal is a fact about your configuration, and gone would delete the registration.
• createExpoSender({ accessToken?, placeholderTitle?, runtime? }) — a WakeSender for the Expo Push API. A plain fetch call against https://exp.host/--/api/v2/push/send; no expo-server-sdk dependency.

Both senders take their fetch from runtime, defaulting to @sozai/runtime's createRuntime(). Pass one to point them at a different HTTP stack, or to capture requests in a test.

Both senders return a WakeVerdict ('delivered' | 'gone' | 'retry') and never throw.

Wiring

import { createMemoryWakeRegistry, createWebPushSender } from '@kumiai/hub-wake'
import { createHub } from '@kumiai/hub-server'

const wake = {
  registry: createMemoryWakeRegistry(),
  sender: createWebPushSender({
    vapid: { subject: 'mailto:[email protected]', privateKey, publicKey },
  }),
  // debounceMs: 10_000, // default
}

const hub = createHub({ transport, store, identity, wake })

With wake omitted, hub/v1/wake/register and hub/v1/wake/unregister refuse with WakeNotSupportedError.

Not in this package

• A durable WakeRegistry — only the in-memory one ships here.
• APNs and FCM senders — both sit behind WakeSender for a host that wants them without Expo in the path.
• The iOS Notification Service Extension — Swift, reached through an Expo config plugin, outside this repo.