Push Notifications: Server API

Pointing at an area

The first argument to sendPush says where the devices are. It's a path, like every other data operation.

What counts as a device

At each node you point at, the engine accepts one of two things:

• A map of devices, like pushTokens below. This is what client.push.enable writes.
• A single device: one subscription object with endpoint and keys.

It doesn't search any deeper. Pointing at ["users"] finds nothing, because the devices are two levels further down. Use the wildcard ["users", "$uid", "pushTokens"] instead. This keeps every send fast: the engine only looks where you told it to, however big the rest of your database is.

"pushTokens": {
  "-u5r83BoVpsmbv4AmSUnmA": {                       // an Android phone (Chrome)
    "endpoint": "https://fcm.googleapis.com/fcm/send/cmJI…",
    "expirationTime": null,
    "keys": { "p256dh": "BDF4XAl5…", "auth": "-u5r83BoVpsmbv4AmSUnmA" }
  },
  "AA6TAGG9CDXjJHKtGKMTjg": {                       // an iPhone (Home Screen app)
    "endpoint": "https://web.push.apple.com/QKVLecOK…",
    "keys": { "p256dh": "BK2nrxlT…", "auth": "AA6TAGG9CDXjJHKtGKMTjg" }
  }
}

Each device is the exact object the browser produces (PushSubscription.toJSON()), stored unchanged and keyed by its auth value. That value is unique per device and stays the same when the device re-subscribes, so turning notifications on twice updates the same entry. If your app already stores subscriptions in this shape, sendPush can use them as they are.

Server API

{
  sent: 2,      // accepted by the push service
  removed: 1,   // devices that are gone (uninstalled, permission revoked); deleted where they were found
  failed: 0     // temporary errors (push service down, rate limited); not retried automatically
}

Send options

The engine serves one route for the browser SDK: GET /push/key, your app's public key. There are no subscribe routes, because saving a device is an ordinary database write. To switch push off completely, set PUSH_DISABLED=1 in your .env and run nukebase env push.

The payload

The whole payload must be 3 KB or less once converted to JSON. sendPush rejects anything bigger with a clear error rather than letting the push service drop it. Send a short message and a url, and let the page load the details.

Rules

Saving a device is a normal write, so your rules decide where each device may be saved. Three common patterns:

module.exports = {
  // 1. Each user saves their own devices
  "users": { "$uid": { "pushTokens": { "write": "$uid == admin.uid" } } },

  // 2. Team members save a device to their team
  "teams": { "$teamId": { "pushTokens": {
    "write": "root.teams[$teamId].members?.[admin.uid] === true"
  } } },

  // 3. No sign-in needed: anyone may add a device, but only something shaped like one
  "fans": { "$device": {
    "write": "true",
    "validate": "newData == null || (typeof newData.endpoint === 'string' && newData.endpoint.startsWith('https://') && newData.keys?.auth === $device)"
  } }
};

Keys

Every app has one VAPID key pair: a public key the browser subscribes with, and a private key that signs each message. You can let the engine make them, or bring your own.

Automatic (the default)

The first time push is used, the engine creates a key pair and stores it in your database at ["_nukebase", "pushKeys"]. Because they're part of your data, the keys are included in daily backups, nukebase backup and restore points, and they move with your data to another region.

_nukebase is ordinary data. Your rules decide who can reach it, like any other path, and rules deny by default, so browsers can't read it unless a rule grants it. Don't write a rule that does: anyone holding the private key and your saved devices could send notifications as your app. Your server code can read, set or remove it:

• Setting a new { publicKey, privateKey } there switches keys at once, with no restart.
• Removing it means a fresh key pair is made the next time push is used, which disconnects every subscribed device.

Your own keys (hardcoded in app.js)

To use keys you already have (from an existing app, web-push or Firebase), or to fix the generated ones in your code, pass them to configurePush near the top of server/app.js. Keys given here always take priority.

configurePush({
  publicKey:  "BPaste-your-65-byte-public-key-here…",   // 65 bytes, base64url
  privateKey: "paste-your-32-byte-private-key-here…",   // 32 bytes, base64url
  contact:    "mailto:hello@pawsbook.com"          // optional
});

When the engine creates keys automatically, the server log shows this exact line, ready to paste. A key that's malformed, or a public and private key that don't belong together, stops your app at startup with a clear message, instead of every send being refused later.

Limits & delivery

• Payload: 3 KB of JSON at most.
• Delivery isn't guaranteed. Phones in low-power mode, Focus modes or with notifications turned off may delay or drop messages silently. The push service only confirms that it accepted a message.
• Offline devices receive the message when they reconnect, if ttl hasn't run out.
• Speed: sends go out 10 at a time. Roughly 1,000 devices take a few seconds, and it doesn't block your app while it runs.
• Wildcards look only at the exact shape you give, so ["users", "$uid", "pushTokens"] reads each user's pushTokens and nothing else of theirs.
• Cost: free to send. Each message is a few KB of outgoing traffic, metered like any other traffic.