strapi-plugin-notifier 1.0.2 → 1.1.0

package/tests/unit/config.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { DEFAULT_SETTINGS, mergeWithDefaults } from '../../server/src/config';
+
+describe('mergeWithDefaults', () => {
+  it('returns all default fields when called with no overrides', () => {
+    const result = mergeWithDefaults();
+    expect(result).toEqual(DEFAULT_SETTINGS);
+  });
+
+  it('includes default merge config', () => {
+    const result = mergeWithDefaults();
+    expect(result.merge).toEqual({
+      enabled: false,
+      windowMinutes: 60,
+      keyFields: ['title', 'type'],
+      countBadge: true,
+      rewriteMessage: false,
+    });
+  });
+
+  it('enables merge when overridden', () => {
+    const result = mergeWithDefaults({ merge: { enabled: true } });
+    expect(result.merge.enabled).toBe(true);
+    expect(result.merge.windowMinutes).toBe(60);
+    expect(result.merge.keyFields).toEqual(['title', 'type']);
+  });
+
+  it('overrides windowMinutes while preserving other merge defaults', () => {
+    const result = mergeWithDefaults({ merge: { windowMinutes: 30 } });
+    expect(result.merge.windowMinutes).toBe(30);
+    expect(result.merge.enabled).toBe(false);
+    expect(result.merge.countBadge).toBe(true);
+  });
+
+  it('replaces keyFields entirely when overridden', () => {
+    const result = mergeWithDefaults({ merge: { keyFields: ['url'] } });
+    expect(result.merge.keyFields).toEqual(['url']);
+  });
+
+  it('applies rewriteMessage override', () => {
+    const result = mergeWithDefaults({ merge: { rewriteMessage: true } });
+    expect(result.merge.rewriteMessage).toBe(true);
+    expect(result.merge.countBadge).toBe(true);
+  });
+
+  it('does not bleed merge config into other sections', () => {
+    const result = mergeWithDefaults({ merge: { enabled: true } });
+    expect(result.retention).toEqual(DEFAULT_SETTINGS.retention);
+    expect(result.delivery).toEqual(DEFAULT_SETTINGS.delivery);
+  });
+
+  it('overrides retention fields independently', () => {
+    const result = mergeWithDefaults({ retention: { maxDays: 30 } });
+    expect(result.retention.maxDays).toBe(30);
+    expect(result.retention.maxPerUser).toBe(DEFAULT_SETTINGS.retention.maxPerUser);
+    expect(result.merge).toEqual(DEFAULT_SETTINGS.merge);
+  });
+
+  it('deeply merges ui accent colours', () => {
+    const result = mergeWithDefaults({ ui: { theme: { accent: { info: '#000' } } } });
+    expect(result.ui.theme.accent.info).toBe('#000');
+    expect(result.ui.theme.accent.error).toBe(DEFAULT_SETTINGS.ui.theme.accent.error);
+  });
+});

package/tests/unit/notification.test.ts

@@ -0,0 +1,263 @@
+import { describe, it, expect, vi } from 'vitest';
+import makeNotificationService from '../../server/src/services/notification';
+import { makeNotificationStrapi, makeDbQuery } from '../helpers';
+import type { MergeConfig } from '../../server/src/config';
+
+const DISABLED_MERGE: MergeConfig = {
+  enabled: false,
+  windowMinutes: 60,
+  keyFields: ['title', 'type'],
+  countBadge: true,
+  rewriteMessage: false,
+};
+
+// ---------------------------------------------------------------------------
+// findByRecipient — opt-out filtering
+// ---------------------------------------------------------------------------
+
+describe('notification.findByRecipient', () => {
+  it('returns empty array without querying DB when globalOptOut is true', async () => {
+    const { strapi, _db } = makeNotificationStrapi({}, { globalOptOut: true });
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    const result = await svc.findByRecipient(1, []);
+
+    expect(result).toEqual([]);
+    expect(_db.findMany).not.toHaveBeenCalled();
+  });
+
+  it('queries DB normally when user has no restrictions', async () => {
+    const rows = [{ id: 1, title: 'Hello', type: 'info' }];
+    const { strapi, _db } = makeNotificationStrapi(
+      { findMany: vi.fn().mockResolvedValue(rows) },
+      { globalOptOut: false, mutedTypes: [] }
+    );
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    const result = await svc.findByRecipient(1, []);
+
+    expect(result).toBe(rows);
+    expect(_db.findMany).toHaveBeenCalledOnce();
+    const call = _db.findMany.mock.calls[0][0];
+    expect(call.where).not.toHaveProperty('type');
+  });
+
+  it('adds $notIn filter for mutedTypes', async () => {
+    const { strapi, _db } = makeNotificationStrapi(
+      {},
+      { globalOptOut: false, mutedTypes: ['info', 'warning'] as any }
+    );
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    await svc.findByRecipient(1, []);
+
+    const where = _db.findMany.mock.calls[0][0].where;
+    expect(where.type).toEqual({ $notIn: ['info', 'warning'] });
+  });
+
+  it('respects page and pageSize', async () => {
+    const { strapi, _db } = makeNotificationStrapi();
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    await svc.findByRecipient(1, [], { page: 3, pageSize: 10 });
+
+    const call = _db.findMany.mock.calls[0][0];
+    expect(call.limit).toBe(10);
+    expect(call.offset).toBe(20);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// countByRecipient / countUnread — opt-out
+// ---------------------------------------------------------------------------
+
+describe('notification.countByRecipient', () => {
+  it('returns 0 without querying DB when globalOptOut is true', async () => {
+    const { strapi, _db } = makeNotificationStrapi({}, { globalOptOut: true });
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    const count = await svc.countByRecipient(1, []);
+
+    expect(count).toBe(0);
+    expect(_db.count).not.toHaveBeenCalled();
+  });
+
+  it('queries DB normally when not opted out', async () => {
+    const { strapi, _db } = makeNotificationStrapi({ count: vi.fn().mockResolvedValue(5) });
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    const count = await svc.countByRecipient(1, []);
+
+    expect(count).toBe(5);
+    expect(_db.count).toHaveBeenCalledOnce();
+  });
+});
+
+describe('notification.countUnread', () => {
+  it('returns 0 without querying DB when globalOptOut is true', async () => {
+    const { strapi, _db } = makeNotificationStrapi({}, { globalOptOut: true });
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    const count = await svc.countUnread(1, []);
+
+    expect(count).toBe(0);
+    expect(_db.count).not.toHaveBeenCalled();
+  });
+
+  it('passes read: false filter when not opted out', async () => {
+    const { strapi, _db } = makeNotificationStrapi({ count: vi.fn().mockResolvedValue(3) });
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    await svc.countUnread(1, []);
+
+    const where = _db.count.mock.calls[0][0].where;
+    expect(where.read).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+
+describe('notification.create', () => {
+  it('stores mergeKey and mergeCount: 1', async () => {
+    const { strapi, _db } = makeNotificationStrapi();
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    await svc.create({ title: 'Test', type: 'info', mergeKey: 'Test\x00info' });
+
+    const data = _db.create.mock.calls[0][0].data;
+    expect(data.mergeKey).toBe('Test\x00info');
+    expect(data.mergeCount).toBe(1);
+    expect(data.read).toBe(false);
+  });
+
+  it('defaults type to info', async () => {
+    const { strapi, _db } = makeNotificationStrapi();
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    await svc.create({ title: 'Hi' });
+
+    expect(_db.create.mock.calls[0][0].data.type).toBe('info');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// findMergeCandidate
+// ---------------------------------------------------------------------------
+
+describe('notification.findMergeCandidate', () => {
+  it('queries DB with mergeKey, recipientId, and cutoff', async () => {
+    const candidate = { id: 5, mergeCount: 1 };
+    const { strapi, _db } = makeNotificationStrapi({
+      findOne: vi.fn().mockResolvedValue(candidate),
+    });
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    const before = Date.now();
+    const result = await svc.findMergeCandidate('Test\x00info', 1, null, 60 * 60 * 1000);
+    const after = Date.now();
+
+    expect(result).toBe(candidate);
+    const where = _db.findOne.mock.calls[0][0].where;
+    expect(where.mergeKey).toBe('Test\x00info');
+    expect(where.recipientId).toBe(1);
+    expect(where.recipientRole).toBeNull();
+    const cutoffMs = new Date(where.createdAt.$gt).getTime();
+    expect(cutoffMs).toBeGreaterThanOrEqual(before - 60 * 60 * 1000);
+    expect(cutoffMs).toBeLessThanOrEqual(after);
+  });
+
+  it('returns null when no candidate found', async () => {
+    const { strapi } = makeNotificationStrapi({ findOne: vi.fn().mockResolvedValue(null) });
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    const result = await svc.findMergeCandidate('key', null, null, 3600000);
+    expect(result).toBeNull();
+  });
+
+  it('uses recipientRole when provided', async () => {
+    const { strapi, _db } = makeNotificationStrapi();
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    await svc.findMergeCandidate('key', null, 'strapi-editor', 3600000);
+
+    const where = _db.findOne.mock.calls[0][0].where;
+    expect(where.recipientRole).toBe('strapi-editor');
+    expect(where.recipientId).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// mergeInto
+// ---------------------------------------------------------------------------
+
+describe('notification.mergeInto', () => {
+  it('updates mergeCount without rewriting message when rewriteMessage=false', async () => {
+    const { strapi, _db } = makeNotificationStrapi();
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    await svc.mergeInto(5, 3, { ...DISABLED_MERGE, rewriteMessage: false }, 'Test');
+
+    const data = _db.update.mock.calls[0][0].data;
+    expect(data.mergeCount).toBe(3);
+    expect(data.message).toBeUndefined();
+  });
+
+  it('rewrites message when rewriteMessage=true', async () => {
+    const { strapi, _db } = makeNotificationStrapi();
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    await svc.mergeInto(5, 4, { ...DISABLED_MERGE, rewriteMessage: true }, 'Test');
+
+    const data = _db.update.mock.calls[0][0].data;
+    expect(data.mergeCount).toBe(4);
+    expect(data.message).toBe('4× Test');
+  });
+
+  it('targets the correct notification id', async () => {
+    const { strapi, _db } = makeNotificationStrapi();
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    await svc.mergeInto(99, 2, DISABLED_MERGE, 'X');
+
+    expect(_db.update.mock.calls[0][0].where).toEqual({ id: 99 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createMany
+// ---------------------------------------------------------------------------
+
+describe('notification.createMany', () => {
+  it('calls create for each item', async () => {
+    const { strapi, _db } = makeNotificationStrapi();
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    await svc.createMany([
+      { title: 'A', type: 'info' },
+      { title: 'B', type: 'error' },
+    ]);
+
+    expect(_db.create).toHaveBeenCalledTimes(2);
+    const titles = _db.create.mock.calls.map((c: any) => c[0].data.title);
+    expect(titles).toContain('A');
+    expect(titles).toContain('B');
+  });
+
+  it('returns an array of created items', async () => {
+    const { strapi } = makeNotificationStrapi({
+      create: vi
+        .fn()
+        .mockResolvedValueOnce({ id: 1, title: 'A' })
+        .mockResolvedValueOnce({ id: 2, title: 'B' }),
+    });
+    const svc = makeNotificationService({ strapi: strapi as any });
+
+    const results = await svc.createMany([{ title: 'A' }, { title: 'B' }]);
+
+    expect(results).toHaveLength(2);
+    expect(results[0]).toMatchObject({ id: 1 });
+    expect(results[1]).toMatchObject({ id: 2 });
+  });
+});

package/tests/unit/notifier.test.ts

@@ -0,0 +1,348 @@
+import { describe, it, expect, vi } from 'vitest';
+import makeNotifierService from '../../server/src/services/notifier';
+import { makeNotifierStrapi } from '../helpers';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const MERGE_ENABLED = {
+  enabled: true,
+  windowMinutes: 60,
+  keyFields: ['title', 'type'],
+  countBadge: true,
+  rewriteMessage: false,
+};
+
+const MERGE_DISABLED = { ...MERGE_ENABLED, enabled: false };
+
+const withMerge = (enabled: boolean, extra = {}) => ({
+  merge: enabled ? MERGE_ENABLED : MERGE_DISABLED,
+  ...extra,
+});
+
+// ---------------------------------------------------------------------------
+// send — merge disabled
+// ---------------------------------------------------------------------------
+
+describe('notifier.send — merge disabled', () => {
+  it('creates a notification directly', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.send({ title: 'Hello', type: 'info' });
+
+    expect(_notifSvc.create).toHaveBeenCalledOnce();
+    expect(_notifSvc.findMergeCandidate).not.toHaveBeenCalled();
+  });
+
+  it('passes title, message, type, url to create', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.send({ title: 'T', message: 'M', type: 'error', url: '/path' });
+
+    const args = _notifSvc.create.mock.calls[0][0];
+    expect(args).toMatchObject({ title: 'T', message: 'M', type: 'error', url: '/path' });
+  });
+
+  it('sets recipientId when targeting a user', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.send({ title: 'Hi', to: { userId: 42 } });
+
+    expect(_notifSvc.create.mock.calls[0][0].recipientId).toBe(42);
+  });
+
+  it('sets recipientRole when targeting a role', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.send({ title: 'Hi', to: { role: 'strapi-editor' } });
+
+    expect(_notifSvc.create.mock.calls[0][0].recipientRole).toBe('strapi-editor');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// send — opt-out
+// ---------------------------------------------------------------------------
+
+describe('notifier.send — opt-out', () => {
+  it('does not create when target user is opted out (globalOptOut)', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi(
+      {},
+      { globalOptOut: true }
+    );
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    const result = await svc.toUser(1, { title: 'Hi' });
+
+    expect(result).toBeNull();
+    expect(_notifSvc.create).not.toHaveBeenCalled();
+  });
+
+  it('does not create when type is muted', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi(
+      {},
+      { globalOptOut: false, mutedTypes: ['info'] as any }
+    );
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    const result = await svc.toUser(1, { title: 'Hi', type: 'info' });
+
+    expect(result).toBeNull();
+    expect(_notifSvc.create).not.toHaveBeenCalled();
+  });
+
+  it('creates when type is NOT in mutedTypes', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi(
+      {},
+      { globalOptOut: false, mutedTypes: ['warning'] as any }
+    );
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.toUser(1, { title: 'Hi', type: 'info' });
+
+    expect(_notifSvc.create).toHaveBeenCalledOnce();
+  });
+
+  it('does NOT check opt-out for broadcast (no recipientId)', async () => {
+    const { strapi, _notifSvc, _prefSvc, _settSvc } = makeNotifierStrapi(
+      {},
+      { globalOptOut: true }
+    );
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.broadcast({ title: 'All' });
+
+    expect(_prefSvc.get).not.toHaveBeenCalled();
+    expect(_notifSvc.create).toHaveBeenCalledOnce();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// send — merge enabled
+// ---------------------------------------------------------------------------
+
+describe('notifier.send — merge enabled', () => {
+  it('calls findMergeCandidate with computed merge key', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(true));
+    _notifSvc.findMergeCandidate.mockResolvedValue(null);
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.send({ title: 'Deploy', type: 'info' });
+
+    expect(_notifSvc.findMergeCandidate).toHaveBeenCalledOnce();
+    const [mergeKey] = _notifSvc.findMergeCandidate.mock.calls[0];
+    expect(mergeKey).toBe('Deploy\x00info');
+  });
+
+  it('calls mergeInto (not create) when a candidate is found', async () => {
+    const candidate = { id: 7, mergeCount: 2 };
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(true));
+    _notifSvc.findMergeCandidate.mockResolvedValue(candidate);
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.send({ title: 'Deploy', type: 'info' });
+
+    expect(_notifSvc.mergeInto).toHaveBeenCalledWith(7, 3, MERGE_ENABLED, 'Deploy');
+    expect(_notifSvc.create).not.toHaveBeenCalled();
+  });
+
+  it('creates a new notification when no candidate found', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(true));
+    _notifSvc.findMergeCandidate.mockResolvedValue(null);
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.send({ title: 'New', type: 'success' });
+
+    expect(_notifSvc.create).toHaveBeenCalledOnce();
+    expect(_notifSvc.mergeInto).not.toHaveBeenCalled();
+  });
+
+  it('includes mergeKey in the created notification', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(true));
+    _notifSvc.findMergeCandidate.mockResolvedValue(null);
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.send({ title: 'Test', type: 'warning' });
+
+    const args = _notifSvc.create.mock.calls[0][0];
+    expect(args.mergeKey).toBe('Test\x00warning');
+  });
+
+  it('uses configured keyFields to build merge key', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue({
+      merge: { ...MERGE_ENABLED, keyFields: ['title', 'url'] },
+    });
+    _notifSvc.findMergeCandidate.mockResolvedValue(null);
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.send({ title: 'Deploy', url: '/admin', type: 'info' });
+
+    const [mergeKey] = _notifSvc.findMergeCandidate.mock.calls[0];
+    expect(mergeKey).toBe('Deploy\x00/admin');
+  });
+
+  it('passes window in ms to findMergeCandidate', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue({
+      merge: { ...MERGE_ENABLED, windowMinutes: 30 },
+    });
+    _notifSvc.findMergeCandidate.mockResolvedValue(null);
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.send({ title: 'T', type: 'info' });
+
+    const windowMs = _notifSvc.findMergeCandidate.mock.calls[0][3];
+    expect(windowMs).toBe(30 * 60 * 1000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// sendBatch
+// ---------------------------------------------------------------------------
+
+describe('notifier.sendBatch', () => {
+  it('fetches settings exactly once regardless of batch size', async () => {
+    const { strapi, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.sendBatch([
+      { title: 'A', type: 'info' },
+      { title: 'B', type: 'warning' },
+      { title: 'C', type: 'success' },
+    ]);
+
+    expect(_settSvc.getEffective).toHaveBeenCalledOnce();
+  });
+
+  it('sends all items and returns an array of results', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+    _notifSvc.create
+      .mockResolvedValueOnce({ id: 1 })
+      .mockResolvedValueOnce({ id: 2 });
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    const results = await svc.sendBatch([
+      { title: 'A', type: 'info' },
+      { title: 'B', type: 'error' },
+    ]);
+
+    expect(_notifSvc.create).toHaveBeenCalledTimes(2);
+    expect(results).toHaveLength(2);
+  });
+
+  it('skips opted-out recipients but still sends others', async () => {
+    const { strapi, _notifSvc, _prefSvc, _settSvc } = makeNotifierStrapi(
+      {},
+      { globalOptOut: true }
+    );
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    const results = await svc.sendBatch([
+      { title: 'A', to: { userId: 1 } },
+      { title: 'B' },
+    ]);
+
+    // userId:1 opted out → null; broadcast (no userId) → not checked
+    expect(results[0]).toBeNull();
+    expect(_notifSvc.create).toHaveBeenCalledOnce();
+    expect(results).toHaveLength(2);
+  });
+
+  it('returns empty array for empty input', async () => {
+    const { strapi, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    const results = await svc.sendBatch([]);
+
+    expect(results).toEqual([]);
+    expect(_settSvc.getEffective).toHaveBeenCalledOnce();
+  });
+
+  it('applies merge per item in the batch', async () => {
+    const candidate = { id: 10, mergeCount: 1 };
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(true));
+    _notifSvc.findMergeCandidate
+      .mockResolvedValueOnce(candidate)
+      .mockResolvedValueOnce(null);
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.sendBatch([
+      { title: 'Same', type: 'info' },
+      { title: 'New', type: 'info' },
+    ]);
+
+    expect(_notifSvc.mergeInto).toHaveBeenCalledOnce();
+    expect(_notifSvc.create).toHaveBeenCalledOnce();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// toUser / toRole / broadcast convenience wrappers
+// ---------------------------------------------------------------------------
+
+describe('notifier convenience wrappers', () => {
+  it('toUser passes recipientId and skips create when opted out', async () => {
+    const { strapi, _notifSvc, _settSvc } = makeNotifierStrapi(
+      {},
+      { globalOptOut: true }
+    );
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.toUser(1, { title: 'Hi' });
+
+    expect(_notifSvc.create).not.toHaveBeenCalled();
+  });
+
+  it('toRole passes recipientRole without opt-out check', async () => {
+    const { strapi, _notifSvc, _prefSvc, _settSvc } = makeNotifierStrapi(
+      {},
+      { globalOptOut: true }
+    );
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.toRole('strapi-editor', { title: 'Hi' });
+
+    expect(_prefSvc.get).not.toHaveBeenCalled();
+    expect(_notifSvc.create).toHaveBeenCalledOnce();
+    expect(_notifSvc.create.mock.calls[0][0].recipientRole).toBe('strapi-editor');
+  });
+
+  it('broadcast creates without opt-out check', async () => {
+    const { strapi, _notifSvc, _prefSvc, _settSvc } = makeNotifierStrapi();
+    _settSvc.getEffective.mockResolvedValue(withMerge(false));
+
+    const svc = makeNotifierService({ strapi: strapi as any });
+    await svc.broadcast({ title: 'All', type: 'warning' });
+
+    expect(_prefSvc.get).not.toHaveBeenCalled();
+    expect(_notifSvc.create).toHaveBeenCalledOnce();
+    const args = _notifSvc.create.mock.calls[0][0];
+    expect(args.recipientId).toBeUndefined();
+    expect(args.recipientRole).toBeUndefined();
+  });
+});