@fayz-ai/plugin-notifications 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faya Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @fayz-ai/plugin-notifications
+
+> The engine that turns a fact into a message: template, queue, retry, deduplication
+> and the recipient's choice of channel.
+
+[![npm](https://img.shields.io/npm/v/@fayz-ai/plugin-notifications.svg)](https://www.npmjs.com/package/@fayz-ai/plugin-notifications)
+[![license](https://img.shields.io/npm/l/@fayz-ai/plugin-notifications.svg)](https://github.com/FayaLabs/fayz-sdk/blob/main/LICENSE)
+
+**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
+
+```bash
+npm install @fayz-ai/plugin-notifications
+```
+
+```ts
+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
+
+```sql
+-- 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.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import type { PluginManifest, PluginScope, VerticalId } from '@fayz-ai/core';
+export interface NotificationsPluginOptions {
+    scope?: PluginScope;
+    verticalId?: VerticalId;
+    /** Label override for the module name shown in settings and navigation. */
+    name?: string;
+}
+/**
+ * The engine dunning, appointment confirmation, order-ready, the post-service
+ * survey and a marketing campaign all share. What varies between them is the
+ * template; what does not vary is the queue, the retry, the deduplication and
+ * the recipient's right to choose the channel — so it is built once, here.
+ *
+ * The plugin ships no screen of its own yet: everything it does is reachable
+ * from SQL (`notifications_enqueue`, `notifications_drain`) and from the event
+ * subscriptions it declares. The admin surface is a follow-up, and shipping the
+ * engine without it is deliberate — a campaign form that cannot send is what
+ * this phase exists to stop building.
+ */
+export declare function createNotificationsPlugin(options?: NotificationsPluginOptions): PluginManifest;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAK5E,MAAM,WAAW,0BAA0B;IACzC,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,cAAc,CAuD9F"}