@fayz-ai/plugin-notifications

The engine that turns a fact into a message: template, queue, retry, deduplication and the recipient's choice of channel.

Status: beta — the engine is complete and graded by the canonical chain (schema, enqueue, dedupe, opt-out, drain). Pre-1.0: no admin surface yet, and the APIs may change before 1.0.

Install

npm install @fayz-ai/plugin-notifications

import { createNotificationsPlugin } from '@fayz-ai/plugin-notifications'

export const plugins = [createNotificationsPlugin()]

createNotificationsPlugin mounts no screen. Everything it does is reachable from SQL and from the three event subscriptions it declares — which is deliberate: a form that cannot send is what this engine exists to stop shipping.

Why it exists

The SDK had both ends and not the middle. It had the event — the durable log and its consumer — and it had the channel: plugin-conversations owns the number, the delivery and the opt-out. public.notifications is a bell inside the app that never leaves it. So "tell the customer their order is ready" had nowhere to live.

Dunning, appointment confirmation, order-ready, the post-service survey and a marketing campaign are the same engine with a different template. This is that engine.

What it ships

| Table | What it holds | |---|---| | plg_notifications_templates | what a message says, per key, channel and locale | | plg_notifications_preferences | how a person wants to be reached | | plg_notifications_queue | what is waiting, what went, and what was refused and why | | plg_notifications_deliveries | what the provider said | | plg_notifications_channels | which function delivers a channel, per tenant |

The three invariants

1. Nothing leaves without a template. notifications_enqueue refuses a key it cannot resolve, before writing anything.
2. Opt-out is an absolute veto, and a blocked message is a ROW with a reason on it — an opt-out that produces nothing at all is indistinguishable from an engine that quietly stopped working.
3. Redelivering an event does not send twice. dedupe_key is unique per tenant, so a retried delivery resolves to the message that already exists.

Using it

-- write the template once
INSERT INTO public.plg_notifications_templates (tenant_id, key, channel, body, is_default)
VALUES (:tenant, 'order.completed', 'whatsapp', 'Oi {{customer_name}}, seu pedido {{order_number}} está pronto!', true);

-- everything else is a reaction: the order completes, the engine enqueues
SELECT public.consume_event_log(200);   -- scheduled by pg_cron (PRD 10)
SELECT public.notifications_drain(100); -- its own job: the provider is outside

The drain is a separate schedule from consume_event_log() on purpose: the provider is outside and the queue is ours, so a provider timing out costs a retry here and never holds up the event log.