feat(firebase): support FCM condition addressing in FirebaseDestination

The format callback may now return a non-empty `condition` (an FCM condition
expression over up to 5 topics, e.g. "'A' in topics && !('B' in topics)"). When
present the message is sent with `condition` and WITHOUT `topic` (FCM accepts one
or the other, never both); an absent/empty condition falls back to the normal topic
send, so existing formatters are unaffected. Enables targeting a combination of
topics — e.g. a topic's subscribers minus those also on another topic.

Bump to 0.7.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Herklos

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.7.0] — 2026-05-29
+
+### Added
+- **FCM condition addressing in `FirebaseDestination`** — the `format` callback may now return a non-empty `condition` (an [FCM condition expression](https://firebase.google.com/docs/cloud-messaging/send-message#send_messages_to_topics), boolean over up to 5 topics, e.g. `"'A' in topics && !('B' in topics)"`). When present, the message is sent with `condition` and **without** `topic` (FCM accepts one or the other, never both); an absent or empty-string `condition` falls back to the normal topic send, so existing formatters are unaffected. This enables targeting a *combination* of topics — e.g. delivering to a topic's subscribers while excluding those also subscribed to another topic. `topic` still cannot be set by `format` (it is stripped, as before).
+
+### Changed
+- `FirebaseDestination.send` strips both `topic` and `condition` from the formatted body before re-applying exactly one: `condition` when non-empty, otherwise the subscription's `topic`.
+
 ## [0.6.0] — 2026-05-23
 
 ### Added

README.md

@@ -226,7 +226,28 @@ new FirebaseDestination({
 })
 ```
 
-`topic` is always set from the subscription config and cannot be overridden by `format`.
+`topic` is set from the subscription config and cannot be overridden by `format`.
+
+To target a **combination of topics** instead of a single one, return a non-empty
+`condition` from `format` — an [FCM condition expression](https://firebase.google.com/docs/cloud-messaging/send-message#send_messages_to_topics)
+(boolean over up to 5 topics). When present it is sent as `condition` and the
+`topic` is omitted (FCM accepts one or the other, never both); an absent/empty
+`condition` falls back to the normal topic send:
+
+```typescript
+// deliver to everyone subscribed to the space topic EXCEPT the author's own devices
+new FirebaseDestination({
+  format: (n) => {
+    const authorId = (n.rawPayload as { identity?: string }).identity
+    return {
+      notification: { title: "New message" },
+      ...(authorId
+        ? { condition: `'${n.topic}' in topics && !('user-${authorId}' in topics)` }
+        : {}), // no identity → plain topic send (backward-compatible)
+    }
+  },
+})
+```
 
 ```
 pnpm add firebase-admin

packages/ts/whistlers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/whistlers",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Message-queue to destination bridge — Firebase, ClickHouse, PostgreSQL, S3, SSE",
   "type": "module",
   "main": "dist/index.js",

packages/ts/whistlers/src/destination/firebase.ts

@@ -8,14 +8,19 @@ export interface FirebaseDestinationOptions {
   app?: import("firebase-admin/app").App
   /**
    * Format the FCM message body. Receives the outgoing notification and returns an object
-   * that is spread into the FCM message alongside `topic` (which is always set from
-   * `notification.topic` and cannot be overridden — a `topic` key in the return value is
-   * silently ignored).
+   * that is spread into the FCM message alongside `topic` (which is set from
+   * `notification.topic` — a `topic` key in the return value is silently ignored).
    *
    * Standard keys: `notification` (`{title?, body?}`), `data` (`Record<string, string>` —
    * FCM requires string values). Additional FCM-specific keys (android, apns, webpush,
    * fcmOptions, etc.) are also accepted.
    *
+   * Returning a non-empty string `condition` switches addressing from topic to an FCM
+   * condition expression (e.g. `"'A' in topics && !('B' in topics)"`, up to 5 topics):
+   * the message is then sent with `condition` and WITHOUT `topic` (FCM rejects both at
+   * once). An absent/empty `condition` falls back to the default topic send, so a
+   * formatter can opt into exclusion per-message and otherwise behave as before.
+   *
    * When omitted, `notification` and `data` are forwarded from the incoming notification.
    */
   format?: (notification: OutgoingNotification) => Record<string, unknown>
@@ -49,6 +54,15 @@ export class FirebaseDestination implements DestinationAdapter {
             : {}),
         }
 
-    await messaging.send({ ...body, topic: notification.topic })
+    // A formatter may return a `condition` (FCM topic-combination expression) to
+    // exclude/combine topics. FCM accepts EITHER `topic` OR `condition`, never both,
+    // so a non-empty condition replaces the topic; otherwise we send by topic. The
+    // formatter can never set `topic` directly (stripped here, as documented).
+    const { condition, topic: _ignoredTopic, ...rest } = body
+    await messaging.send(
+      typeof condition === "string" && condition.length > 0
+        ? { ...rest, condition }
+        : { ...rest, topic: notification.topic },
+    )
   }
 }

packages/ts/whistlers/tests/destination/firebase.test.ts

@@ -111,6 +111,26 @@ describe("FirebaseDestination", () => {
     expect(mockSend).toHaveBeenCalledWith(expect.objectContaining({ topic: "orders" }))
   })
 
+  it("sends with condition (and no topic) when format returns a condition", async () => {
+    const condition = "'orders' in topics && !('user-7' in topics)"
+    const format = vi.fn().mockReturnValue({ data: { id: "1" }, condition })
+    const dest = new FirebaseDestination({ format })
+    await dest.send(makeNotification({ topic: "orders" }))
+    const call = mockSend.mock.calls[0]?.[0] as Record<string, unknown>
+    expect(call?.["condition"]).toBe(condition)
+    expect(call?.["topic"]).toBeUndefined()
+    expect(call?.["data"]).toEqual({ id: "1" })
+  })
+
+  it("falls back to topic send when condition is empty", async () => {
+    const format = vi.fn().mockReturnValue({ data: {}, condition: "" })
+    const dest = new FirebaseDestination({ format })
+    await dest.send(makeNotification({ topic: "orders" }))
+    const call = mockSend.mock.calls[0]?.[0] as Record<string, unknown>
+    expect(call?.["topic"]).toBe("orders")
+    expect(call?.["condition"]).toBeUndefined()
+  })
+
   it("propagates errors thrown by format callback", async () => {
     const format = vi.fn().mockImplementation(() => {
       throw new Error("formatter crashed")