@vex-chat/spire 1.10.4 → 1.11.0

package/src/__tests__/notifyFanout.spec.ts

@@ -5,11 +5,12 @@
  */
 
 import type { ClientManager } from "../ClientManager.ts";
+import type { Database, NotificationSubscription } from "../Database.ts";
 import type { BaseMsg } from "@vex-chat/types";
 
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { Spire } from "../Spire.ts";
+import { NotificationService } from "../NotificationService.ts";
 
 interface FakeClient {
     getDeviceID: () => null | string;
@@ -18,21 +19,44 @@ interface FakeClient {
     send: (msg: BaseMsg) => void;
 }
 
-type NotifyFn = (
-    userID: string,
-    event: string,
-    transmissionID: string,
-    data?: unknown,
-    deviceID?: string,
-) => void;
-
-function createSpireHarness(clients: FakeClient[]) {
-    const spire = Object.create(Spire.prototype) as {
-        clients: ClientManager[];
-        notify: NotifyFn;
+const subscription: NotificationSubscription = {
+    channel: "expo",
+    createdAt: "2026-05-12T00:00:00.000Z",
+    deviceID: "device-b",
+    enabled: true,
+    events: ["mail"],
+    platform: "android",
+    subscriptionID: "sub-b",
+    token: "ExponentPushToken[test]",
+    updatedAt: "2026-05-12T00:00:00.000Z",
+    userID: "user-b",
+};
+
+function createSpireHarness(
+    clients: FakeClient[],
+    subscriptions: NotificationSubscription[] = [],
+    removeNotificationSubscription = vi.fn(() => Promise.resolve(true)),
+) {
+    const retrieveNotificationSubscriptions = vi.fn(() =>
+        Promise.resolve(subscriptions),
+    );
+    const db = {
+        removeNotificationSubscription,
+        retrieveNotificationSubscriptions,
+    } as unknown as Database;
+    const managers = clients as unknown as ClientManager[];
+    const removeClient = (client: ClientManager) => {
+        const idx = managers.indexOf(client);
+        if (idx >= 0) managers.splice(idx, 1);
+    };
+    const notifications = new NotificationService(db, managers, removeClient);
+    return {
+        clients: managers,
+        db,
+        notifications,
+        removeNotificationSubscription,
+        retrieveNotificationSubscriptions,
     };
-    spire.clients = clients as unknown as ClientManager[];
-    return spire;
 }
 
 function fakeClient(overrides: Partial<FakeClient> = {}): FakeClient {
@@ -45,7 +69,20 @@ function fakeClient(overrides: Partial<FakeClient> = {}): FakeClient {
     };
 }
 
+function pendingReceiptCount(service: NotificationService): number {
+    return (
+        service as unknown as {
+            pendingReceipts: Map<string, unknown>;
+        }
+    ).pendingReceipts.size;
+}
+
 describe("Spire notify fanout", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+
     it("continues device fanout after pruning a stale client", () => {
         const stale = fakeClient({
             getDeviceID: vi.fn(() => null),
@@ -56,19 +93,23 @@ describe("Spire notify fanout", () => {
         const other = fakeClient({
             getDeviceID: vi.fn(() => "device-c"),
         });
-        const spire = createSpireHarness([stale, recipient, other]);
+        const { clients, notifications } = createSpireHarness([
+            stale,
+            recipient,
+            other,
+        ]);
 
-        spire.notify(
-            "user-b",
-            "mail",
-            "00000000-0000-0000-0000-000000000001",
-            null,
-            "device-b",
-        );
+        notifications.notify({
+            data: null,
+            deviceID: "device-b",
+            event: "mail",
+            transmissionID: "00000000-0000-0000-0000-000000000001",
+            userID: "user-b",
+        });
 
         expect(recipient.send).toHaveBeenCalledTimes(1);
         expect(other.send).not.toHaveBeenCalled();
-        expect(spire.clients).toEqual([recipient, other]);
+        expect(clients).toEqual([recipient, other]);
     });
 
     it("continues user fanout after a client inspection throws", () => {
@@ -83,16 +124,340 @@ describe("Spire notify fanout", () => {
         const other = fakeClient({
             getUserID: vi.fn(() => "user-c"),
         });
-        const spire = createSpireHarness([broken, recipient, other]);
+        const { clients, notifications } = createSpireHarness([
+            broken,
+            recipient,
+            other,
+        ]);
 
-        spire.notify(
-            "user-b",
-            "device_pending_enrollment",
-            "00000000-0000-0000-0000-000000000002",
-        );
+        notifications.notify({
+            event: "device_pending_enrollment",
+            transmissionID: "00000000-0000-0000-0000-000000000002",
+            userID: "user-b",
+        });
 
         expect(recipient.send).toHaveBeenCalledTimes(1);
         expect(other.send).not.toHaveBeenCalled();
-        expect(spire.clients).toEqual([recipient, other]);
+        expect(clients).toEqual([recipient, other]);
+    });
+
+    it("uses headless Expo pushes for sender-owned mail while keeping websocket fanout", async () => {
+        const recipient = fakeClient({
+            getDeviceID: vi.fn(() => "device-b"),
+        });
+        const fetchMock = vi.fn().mockResolvedValueOnce({
+            json: () =>
+                Promise.resolve({
+                    data: [{ id: "receipt-a", status: "ok" }],
+                }),
+            ok: true,
+        });
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { notifications, retrieveNotificationSubscriptions } =
+            createSpireHarness([recipient], [subscription]);
+
+        notifications.notify({
+            deviceID: "device-b",
+            event: "mail",
+            headlessPushUserID: "user-b",
+            transmissionID: "00000000-0000-0000-0000-000000000007",
+            userID: "user-b",
+        });
+
+        expect(recipient.send).toHaveBeenCalledTimes(1);
+        await vi.waitFor(() => {
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+        });
+        expect(retrieveNotificationSubscriptions).toHaveBeenCalledWith({
+            deviceID: "device-b",
+            event: "mail",
+            userID: "user-b",
+        });
+
+        const init = fetchMock.mock.calls[0]?.[1] as
+            | undefined
+            | { body?: unknown };
+        const messages = JSON.parse(String(init?.body)) as Array<{
+            _contentAvailable?: boolean;
+            body?: string;
+            channelId?: string;
+            data?: Record<string, unknown>;
+            tag?: string;
+            title?: string;
+        }>;
+        expect(messages[0]?._contentAvailable).toBe(true);
+        expect(messages[0]).not.toHaveProperty("body");
+        expect(messages[0]).not.toHaveProperty("channelId");
+        expect(messages[0]).not.toHaveProperty("tag");
+        expect(messages[0]).not.toHaveProperty("title");
+        expect(messages[0]?.data).toMatchObject({
+            deviceID: "device-b",
+            event: "mail",
+            headless: true,
+            transmissionID: "00000000-0000-0000-0000-000000000007",
+        });
+    });
+
+    it("checks Expo receipts and removes unregistered devices", async () => {
+        vi.useFakeTimers();
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce({
+                json: () =>
+                    Promise.resolve({
+                        data: [{ id: "receipt-a", status: "ok" }],
+                    }),
+                ok: true,
+            })
+            .mockResolvedValueOnce({
+                json: () =>
+                    Promise.resolve({
+                        data: {
+                            "receipt-a": {
+                                details: { error: "DeviceNotRegistered" },
+                                message: "device is not registered",
+                                status: "error",
+                            },
+                        },
+                    }),
+                ok: true,
+            });
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { db, removeNotificationSubscription } = createSpireHarness(
+            [],
+            [subscription],
+        );
+        const service = new NotificationService(db, [], () => {}, {
+            receiptDelayMs: 1,
+        });
+
+        service.notify({
+            deviceID: subscription.deviceID,
+            event: "mail",
+            transmissionID: "00000000-0000-0000-0000-000000000003",
+            userID: subscription.userID,
+        });
+
+        await vi.advanceTimersByTimeAsync(1);
+
+        await vi.waitFor(() => {
+            expect(fetchMock).toHaveBeenCalledTimes(2);
+        });
+        expect(fetchMock.mock.calls[1]?.[0]).toBe(
+            "https://exp.host/--/api/v2/push/getReceipts",
+        );
+        expect(removeNotificationSubscription).toHaveBeenCalledWith({
+            deviceID: subscription.deviceID,
+            subscriptionID: subscription.subscriptionID,
+            userID: subscription.userID,
+        });
+    });
+
+    it("does not leave stale pending receipts after receipt lookup failure", async () => {
+        vi.useFakeTimers();
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce({
+                json: () =>
+                    Promise.resolve({
+                        data: [{ id: "receipt-a", status: "ok" }],
+                    }),
+                ok: true,
+            })
+            .mockResolvedValueOnce({
+                ok: false,
+                status: 503,
+            });
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { db } = createSpireHarness([], [subscription]);
+        const service = new NotificationService(db, [], () => {}, {
+            receiptDelayMs: 1,
+        });
+
+        service.notify({
+            deviceID: subscription.deviceID,
+            event: "mail",
+            transmissionID: "00000000-0000-0000-0000-000000000004",
+            userID: subscription.userID,
+        });
+
+        await vi.advanceTimersByTimeAsync(1);
+
+        await vi.waitFor(() => {
+            expect(fetchMock).toHaveBeenCalledTimes(2);
+            expect(pendingReceiptCount(service)).toBe(0);
+        });
+    });
+
+    it("does not leave stale pending receipts after receipt fetch rejection", async () => {
+        vi.useFakeTimers();
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce({
+                json: () =>
+                    Promise.resolve({
+                        data: [{ id: "receipt-a", status: "ok" }],
+                    }),
+                ok: true,
+            })
+            .mockRejectedValueOnce(new Error("network unavailable"));
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { db } = createSpireHarness([], [subscription]);
+        const service = new NotificationService(db, [], () => {}, {
+            receiptDelayMs: 1,
+        });
+
+        service.notify({
+            deviceID: subscription.deviceID,
+            event: "mail",
+            transmissionID: "00000000-0000-0000-0000-000000000008",
+            userID: subscription.userID,
+        });
+
+        await vi.advanceTimersByTimeAsync(1);
+
+        await vi.waitFor(() => {
+            expect(fetchMock).toHaveBeenCalledTimes(2);
+            expect(pendingReceiptCount(service)).toBe(0);
+        });
+    });
+
+    it("does not leave stale pending receipts after receipt lookup timeout", async () => {
+        vi.useFakeTimers();
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce({
+                json: () =>
+                    Promise.resolve({
+                        data: [{ id: "receipt-a", status: "ok" }],
+                    }),
+                ok: true,
+            })
+            .mockImplementationOnce((_input: string, init?: RequestInit) => {
+                return new Promise<Response>((_resolve, reject) => {
+                    const abortError = new Error("aborted");
+                    abortError.name = "AbortError";
+                    const signal = init?.signal;
+                    if (signal?.aborted) {
+                        reject(abortError);
+                        return;
+                    }
+                    signal?.addEventListener(
+                        "abort",
+                        () => {
+                            reject(abortError);
+                        },
+                        { once: true },
+                    );
+                });
+            });
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { db } = createSpireHarness([], [subscription]);
+        const service = new NotificationService(db, [], () => {}, {
+            receiptDelayMs: 1,
+        });
+
+        service.notify({
+            deviceID: subscription.deviceID,
+            event: "mail",
+            transmissionID: "00000000-0000-0000-0000-000000000009",
+            userID: subscription.userID,
+        });
+
+        await vi.advanceTimersByTimeAsync(1);
+        await vi.waitFor(() => {
+            expect(fetchMock).toHaveBeenCalledTimes(2);
+        });
+        await vi.advanceTimersByTimeAsync(10_000);
+
+        await vi.waitFor(() => {
+            expect(pendingReceiptCount(service)).toBe(0);
+        });
+    });
+
+    it("sends Android Expo pushes on the mobile push channel", async () => {
+        const fetchMock = vi.fn().mockResolvedValueOnce({
+            json: () =>
+                Promise.resolve({
+                    data: [{ id: "receipt-a", status: "ok" }],
+                }),
+            ok: true,
+        });
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { db } = createSpireHarness([], [subscription]);
+        const service = new NotificationService(db, [], () => {});
+
+        await service["notifyPush"]({
+            deviceID: subscription.deviceID,
+            event: "mail",
+            transmissionID: "00000000-0000-0000-0000-000000000006",
+            userID: subscription.userID,
+        });
+
+        const init = fetchMock.mock.calls[0]?.[1] as
+            | undefined
+            | { body?: unknown };
+        const messages = JSON.parse(String(init?.body)) as Array<{
+            channelId?: string;
+            collapseId?: string;
+            data?: Record<string, unknown>;
+            priority?: string;
+            tag?: string;
+            title?: string;
+        }>;
+        expect(messages[0]?.collapseId).toBe("vex-message-summary");
+        expect(messages[0]?.channelId).toBe("vex-push-messages-v2");
+        expect(messages[0]?.priority).toBe("high");
+        expect(messages[0]?.tag).toBe("vex-message-summary");
+        expect(messages[0]?.title).toBe("New Message");
+        expect(messages[0]).not.toHaveProperty("body");
+        expect(messages[0]?.data).toMatchObject({
+            event: "mail",
+            title: "New Message",
+            transmissionID: "00000000-0000-0000-0000-000000000006",
+        });
+    });
+
+    it("awaits ticket error cleanup so rejection stays on notifyPush", async () => {
+        const cleanupError = new Error("database unavailable");
+        const removeNotificationSubscription = vi.fn(() =>
+            Promise.reject(cleanupError),
+        );
+        const fetchMock = vi.fn().mockResolvedValueOnce({
+            json: () =>
+                Promise.resolve({
+                    data: [
+                        {
+                            details: { error: "DeviceNotRegistered" },
+                            message: "device is not registered",
+                            status: "error",
+                        },
+                    ],
+                }),
+            ok: true,
+        });
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { db } = createSpireHarness(
+            [],
+            [subscription],
+            removeNotificationSubscription,
+        );
+        const service = new NotificationService(db, [], () => {});
+
+        await expect(
+            service["notifyPush"]({
+                deviceID: subscription.deviceID,
+                event: "mail",
+                transmissionID: "00000000-0000-0000-0000-000000000005",
+                userID: subscription.userID,
+            }),
+        ).rejects.toThrow(cleanupError);
     });
 });

package/src/db/schema.ts

@@ -90,8 +90,10 @@ export type NewFile = Insertable<FilesTable>;
 
 export type NewInvite = Insertable<InvitesTable>;
 export type NewMail = Insertable<MailTable>;
-export type NewOneTimeKey = Insertable<OneTimeKeysTable>;
+export type NewNotificationSubscription =
+    Insertable<NotificationSubscriptionsTable>;
 
+export type NewOneTimeKey = Insertable<OneTimeKeysTable>;
 export type NewPasskey = Insertable<PasskeysTable>;
 export type NewPermission = Insertable<PermissionsTable>;
 export type NewPreKey = Insertable<PreKeysTable>;
@@ -99,6 +101,23 @@ export type NewPreKey = Insertable<PreKeysTable>;
 export type NewServer = Insertable<ServersTable>;
 export type NewServiceMetric = Insertable<ServiceMetricsTable>;
 export type NewUser = Insertable<UsersTable>;
+export type NotificationSubscriptionRow =
+    Selectable<NotificationSubscriptionsTable>;
+
+export interface NotificationSubscriptionsTable {
+    channel: string;
+    createdAt: string;
+    deviceID: string;
+    enabled: number;
+    events: string;
+    platform: null | string;
+    subscriptionID: string;
+    token: string;
+    updatedAt: string;
+    userID: string;
+}
+export type NotificationSubscriptionUpdate =
+    Updateable<NotificationSubscriptionsTable>;
 export type OneTimeKeyRow = Selectable<OneTimeKeysTable>;
 
 export interface OneTimeKeysTable {
@@ -153,6 +172,7 @@ export interface ServerDatabase {
     files: FilesTable;
     invites: InvitesTable;
     mail: MailTable;
+    notification_subscriptions: NotificationSubscriptionsTable;
     oneTimeKeys: OneTimeKeysTable;
     passkeys: PasskeysTable;
     permissions: PermissionsTable;

package/src/migrations/2026-05-10_notification-subscriptions.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { Kysely } from "kysely";
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+    await db.schema
+        .dropTable("notification_subscriptions")
+        .ifExists()
+        .execute();
+}
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+    await db.schema
+        .createTable("notification_subscriptions")
+        .ifNotExists()
+        .addColumn("subscriptionID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("userID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("deviceID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("channel", "varchar(32)", (cb) => cb.notNull())
+        .addColumn("token", "text", (cb) => cb.notNull())
+        .addColumn("platform", "varchar(32)")
+        .addColumn("events", "text", (cb) => cb.notNull())
+        .addColumn("enabled", "integer", (cb) => cb.notNull().defaultTo(1))
+        .addColumn("createdAt", "text", (cb) => cb.notNull())
+        .addColumn("updatedAt", "text", (cb) => cb.notNull())
+        .execute();
+
+    await db.schema
+        .createIndex("notification_subscriptions_device_idx")
+        .ifNotExists()
+        .on("notification_subscriptions")
+        .columns(["deviceID", "channel"])
+        .execute();
+
+    await db.schema
+        .createIndex("notification_subscriptions_user_idx")
+        .ifNotExists()
+        .on("notification_subscriptions")
+        .columns(["userID", "channel"])
+        .execute();
+
+    await db.schema
+        .createIndex("notification_subscriptions_token_idx")
+        .ifNotExists()
+        .on("notification_subscriptions")
+        .columns(["channel", "token"])
+        .execute();
+}

package/src/migrations/2026-05-15_notification-subscription-unique-key.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import { type Kysely, sql } from "kysely";
+
+const UNIQUE_INDEX_NAME =
+    "notification_subscriptions_channel_device_token_unique_idx";
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+    await db.schema.dropIndex(UNIQUE_INDEX_NAME).ifExists().execute();
+}
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+    await sql`
+        DELETE FROM notification_subscriptions
+        WHERE rowid NOT IN (
+            SELECT MAX(rowid)
+            FROM notification_subscriptions
+            GROUP BY channel, deviceID, token
+        )
+    `.execute(db);
+
+    await db.schema
+        .createIndex(UNIQUE_INDEX_NAME)
+        .ifNotExists()
+        .on("notification_subscriptions")
+        .columns(["channel", "deviceID", "token"])
+        .unique()
+        .execute();
+}