Add a marketing tool API with marketer keys and audience queries

[peachbits]

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

none

Description

Adds the marketing tool API consumed by the web UI in EdgeApp/edge-internal-tools#1, in three pieces:

• DB helpers: an apiKeyLocation view keyed [apiKey, country, region, city] with a streaming reader, plus a batched-by-id device lookup.
• Marketer keys: API keys gain a marketer flag and a targetApiKeys list. The marketing endpoints require the flag (or admin) and only reach devices registered under the listed keys — the api keys baked into the apps cannot call them, a marketing key can be rotated without an app release, and a key with no targets fails closed.
• The API: POST /marketing/test (single test push), POST /marketing/query (lists the devices a send would reach, filtered by include/exclude lists of cities and regions — lines within a list are alternatives, the lists narrow each other, matching is case-insensitive), and POST /marketing/push (sends to the device list a query returned). The send takes device ids rather than a location so the caller blasts exactly the audience it reviewed, and so a stale server fails loudly (unknown route) instead of resolving the same body to a different audience.

Operational notes: the key doc for the tool needs { marketer: true, targetApiKeys: ["<app api key>"] } in db_api_keys (no adminsdk needed — delivery credentials resolve from each device's own key), and the marketing router parses its own bodies with a 10mb limit ahead of the app-wide 1mb parser.

Tested against a local CouchDB with devices registered through the real /v2/device endpoint: include/exclude query counts, tenant scoping (devices under a second app key never matched), the auth matrix (app key 403, unknown key 401, target-less marketer key 400), and queue publishes for exactly the queried device list. locationFilter has a mocha suite covering the filter and skip-reason logic.

---

Note

Medium Risk
New authenticated bulk-push surface and large-body handling; scoping and marketer flags reduce blast radius, but misconfigured targetApiKeys or operator mistakes could still reach large audiences.

Overview
Adds a marketing tool HTTP API under /marketing for the internal tools UI: POST /marketing/test (single-device or login test push), POST /marketing/query (audience preview by country plus city/region include/exclude lists), and POST /marketing/push (send to an explicit device-id list from a prior query, with confirmed and streaming plain-text progress).

Access control is tightened via API key fields marketer and targetApiKeys: only marketer (or admin) keys can call these routes, and sends only reach devices registered under keys in targetApiKeys—app-embedded keys cannot blast the whole audience. Auth runs before body parsing; the marketing router uses a 10mb JSON limit mounted ahead of the global 1mb parser.

CouchDB gains an apiKeyLocation view and streamDevicesByApiKeyLocation, batched fetchDevicesByIds, and cleaners/types for the new key fields. Location filtering and device skip rules (opt-out, token validity, key scoping) live in locationFilter with mocha tests.

^{Reviewed by Cursor Bugbot for commit 29f2e40. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale comment

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a769049. Configure here.}