strapi-plugin-notifier 1.2.0 → 1.2.1

package/README.md

@@ -10,9 +10,10 @@ A first-class notification system for Strapi v5 admin panels. Adds a live bell i
 - **Batch sending** — send multiple notifications in one call, settings fetched once
 - **Merge** — collapse repeated notifications into one item with a count badge (fully configurable)
 - **User opt-out** — each admin user can mute individual notification types or opt out entirely
-- **Configurable** — poll interval, page size, retention policy, UI accent colours, and merge rules
+- **Declarative rules** — trigger notifications from lifecycle hooks, eventHub events, or cron schedules — no code required beyond `config/plugins.ts`
+- **Configurable** — poll interval, page size, retention policy, UI accent colours, merge rules, and cleanup schedule
 - **Settings panel** — runtime configuration via Settings → Notifier (persisted in Strapi plugin store)
-- **Retention cron** — daily cleanup at 3 AM, respects maxDays and maxPerUser limits
+- **Retention cron** — configurable cleanup schedule (default: 3 AM daily), respects maxDays and maxPerUser limits
 - **Strapi v5 only**
 
 ## Installation
@@ -47,8 +48,9 @@ export default {
     enabled: true,
     config: {
       retention: {
-        maxDays: 90,       // delete notifications older than N days
-        maxPerUser: 500,   // cap notifications stored per user
+        maxDays: 90,          // delete notifications older than N days
+        maxPerUser: 500,      // cap notifications stored per user
+        cleanupCron: '0 3 * * *', // cron schedule for cleanup job (default: 3 AM daily)
       },
       delivery: {
         pollIntervalMs: 30_000, // how often the Bell polls (ms)
@@ -214,6 +216,161 @@ Content-Type: application/json
 | `globalOptOut` | `boolean`          | `false` | Suppress all notifications for this user       |
 | `mutedTypes`   | `NotificationType[]` | `[]`  | Suppress only these notification types        |
 
+## Declarative rules
+
+Instead of calling the notifier service in code, you can declare rules in `config/plugins.ts`. The plugin wires up the listeners at bootstrap — notifications fire automatically with no further code changes needed.
+
+Three trigger types are supported: `lifecycle`, `event`, and `cron`.
+
+### `on: 'lifecycle'` — content-type create/update/delete
+
+Fires when Strapi's DB lifecycle executes for a given content-type and action.
+
+```typescript
+// config/plugins.ts
+notifier: {
+  enabled: true,
+  config: {
+    rules: [
+      {
+        on: 'lifecycle',
+        model: 'api::article.article',
+        action: 'afterCreate',          // afterCreate | afterUpdate | afterDelete | afterPublish | afterUnpublish
+        notification: {
+          title: 'New article: {{entry.title}}',
+          message: 'Created by {{entry.createdBy.firstname}}',
+          type: 'info',
+          to: { role: 'strapi-editor' },
+        },
+      },
+    ],
+  },
+},
+```
+
+`entry` in templates is the DB record produced by the lifecycle action (`result` for after-hooks, `params.data` for before-hooks).
+
+### `on: 'event'` — strapi.eventHub subscription
+
+Fires on any named event published to Strapi's internal event hub (lifecycle events, media events, plugin events, or your own custom events emitted with `strapi.eventHub.emit()`).
+
+```typescript
+{
+  on: 'event',
+  event: 'media.upload',              // any strapi.eventHub event name
+  filter: { uid: 'api::article.article' }, // optional shallow key=value filter on payload
+  notification: {
+    title: 'File uploaded: {{media.name}}',
+    type: 'info',
+    to: 'broadcast',
+  },
+},
+```
+
+**Custom events from your own services:**
+
+```typescript
+// In your service
+strapi.eventHub.emit('order.placed', { order });
+
+// In config/plugins.ts
+{
+  on: 'event',
+  event: 'order.placed',
+  notification: {
+    title: 'New order: #{{order.id}}',
+    message: '{{order.customerName}} — €{{order.total}}',
+    type: 'success',
+    to: { role: 'strapi-super-admin' },
+  },
+},
+```
+
+### `on: 'cron'` — time-based notifications
+
+Fires on a cron schedule. Standard 5-field cron expressions.
+
+```typescript
+{
+  on: 'cron',
+  schedule: '0 9 * * 1',   // Every Monday at 9 AM
+  notification: {
+    title: 'Weekly reminder: review pending content',
+    type: 'warning',
+    to: { role: 'strapi-editor' },
+  },
+},
+```
+
+### Notification templates
+
+Every field in `notification` accepts either a **static value** or a **function** for dynamic content.
+
+**String interpolation** — use `{{path.to.field}}` dot-notation to resolve values from the event context:
+
+```typescript
+notification: {
+  title: 'New order from {{entry.customer.name}}',
+  message: 'Total: {{entry.total}} — shipped to {{entry.address.city}}',
+}
+```
+
+**Function templates** — for logic that can't be expressed as a template string:
+
+```typescript
+notification: {
+  title: (ctx) => `${ctx.entry.priority === 'high' ? '🔴' : ''} Order #${ctx.entry.id}`,
+  type: (ctx) => ctx.entry.priority === 'high' ? 'error' : 'info',
+}
+```
+
+### Targeting in rules
+
+The `to` field supports the same options as the programmatic API, plus a `userIdFrom` path resolver:
+
+| Value                       | Behaviour                                               |
+|-----------------------------|---------------------------------------------------------|
+| `'broadcast'` (or omitted)  | Send to all admin users                                 |
+| `{ role: 'strapi-editor' }` | Send to all users with this role code                   |
+| `{ userId: 42 }`            | Send to a specific admin user                           |
+| `{ userIdFrom: 'entry.createdBy.id' }` | Resolve user ID via dot-path into the event context — useful for "notify the author" patterns |
+
+```typescript
+// Notify the author when their content is rejected
+{
+  on: 'lifecycle',
+  model: 'api::article.article',
+  action: 'afterUpdate',
+  when: (ctx) => ctx.entry.status === 'rejected',
+  notification: {
+    title: 'Your article was rejected',
+    to: { userIdFrom: 'entry.createdBy.id' },
+  },
+},
+```
+
+### `when` guard
+
+Add a `when` function to conditionally skip the notification. Return `false` to suppress it.
+
+```typescript
+{
+  on: 'lifecycle',
+  model: 'api::article.article',
+  action: 'afterUpdate',
+  when: (ctx) => ctx.entry.publishedAt != null,   // only fire when published
+  notification: {
+    title: 'Article published: {{entry.title}}',
+    type: 'success',
+    to: 'broadcast',
+  },
+},
+```
+
+`when` is not available on `cron` rules (there is no event context to filter on).
+
+---
+
 ## API routes
 
 All routes require `admin::isAuthenticatedAdmin`. The plugin mounts under `/notifier/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strapi-plugin-notifier",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "A highly configurable notification inbox plugin for the Strapi v5 admin panel",
   "keywords": [
     "strapi",