Filagora Notifications Laravel Package

Product Decisions This Supports

• Build vs. buy for notification preferences. Storage, defaults/resolution, suppression, unsubscribe links, and privacy export/erasure are commodity plumbing. Adopting this package removes a multi-sprint build from the roadmap and keeps engineering on differentiation. The "differences from the site this was extracted from" section is effectively a free design review — the package has already made the calls (registry over fixed enum, typed exceptions over silent defaults) that an internal build would spend a sprint arguing about.
• Channel expansion. The category registry means adding a notification type or a channel is registration, not a migration or an enum change. This lowers the marginal cost of every future notification on the roadmap and lets the host override a package's category by registering first. Directly supports decisions like "add push next quarter" or "add an in-app bell" without a schema project.
• Consolidating opt-outs across products. The bridges (PushBridge, ForumsBridge, MessagesBridge) make one preferences store authoritative for push, forum subscriptions, and private-message contactability. This is a "one user, one set of choices" product decision, and the bridge design is safe: a host's own binding always wins, and bridges only bind while the sibling's default is still in place.
• Deliverability and unsubscribe compliance. One-click List-Unsubscribe / List-Unsubscribe-Post (RFC 8058), signed links, and the EmailSuppression contract (bounces, complaints, receives_email) support the mailbox-provider requirements that increasingly determine whether transactional and lifecycle mail lands at all. This is a compliance and inbox-placement decision, not a nice-to-have.
• Privacy / DSAR posture. The notifications privacy contributor means export and erasure are handled rather than bespoke. If GDPR/CCPA response is on the roadmap, this closes a gap with zero incremental work.
• Support cost. The read-only relation manager on the user screen (gated by filagora.notifications.view) answers "why didn't this person get that email?" without an engineer. That is a measurable reduction in support-to-engineering escalations.
• Roadmap items this package explicitly creates. Two decisions are now yours: (1) preference-change audit logging is deliberately deferred to a "separate, future package" — if audit is a requirement, it is an open dependency, not a delivered feature; (2) there is no retention rule, and erasure keeps choices a staff member changed for others (minus the link to the erased person). That is a defensible policy but it is a policy the product owner has to sign off on.
• Single source of truth for digest frequency. The package reads digest frequency from the preference row only; the old site also mirrored it into a user column. If any surface still reads that column, keeping it in sync from PreferenceChanged is now an explicit host responsibility — scope it or drop the column.

When to Consider This Package

Adopt when:

• You ship Laravel and have (or are about to have) more than one notification channel — email plus any of push, in-app/bell, or private messages.
• You use Filament for admin and want the preferences screen for free; the relation manager and HasNotificationPreferences trait are the fastest path to support visibility.
• You already use or plan to use the sibling packages (filagora-push, filagora-forums, filagora-messages); the bridges are where most of the integration value sits, and they are opt-out per bridge.
• You need unsubscribe compliance, bounce/complaint suppression, or DSAR export/erasure — these are the parts that are genuinely expensive to build correctly.
• You want per-user defaults plus per-category overrides and per-user resolver logic without inventing a defaults-resolution model.

Look elsewhere, or scope extra work, when:

• You are pre-1.0 risk-averse. This is v0.1.0, a first release, extracted from a single production site. Expect API churn; pin the version and budget for upgrade work.
• Audit is a hard requirement. Regulated (health, finance) or enterprise-procurement contexts that need "who changed what, when" are not served today. That is the future audit package plus your own integration, not this release.
• You need preference changes to drive entitlements or billing. The source site's rule (an entitlement revoked by the inactive-subscriber command) is intentionally left to the host. You will bind your own EmailSuppression; that is real work, not configuration.
• You are porting from the source site and have call sites that rely on lenient behavior. Asking about an unregistered category, an unsupported channel, or a switch-as-mode now throws InvalidPreference where the site answered "on". Audit those call sites before rollout — the failure mode changes from silently-enabled to a thrown exception.
• Your unsubscribe paths are sensitive. Routes are off by default, sit outside the web group, and reuse the exact paths already mailed (email-preferences/unsubscribe/{user}/{category}). Enabling them is a deliberate step; verify path collisions, middleware expectations (no session/auth), and whether unsubscribe.signed_ttl is set to something you can defend.
• You are not on Filament. The relation manager becomes dead weight; the model, service, and privacy contributor still stand on their own.
• You need retention policy enforcement. None is provided; erasure behavior is fixed and you must accept or wrap it.

How to Pitch It (Stakeholders)

For executives: This is a buy-don't-build decision. One package gives us user-facing notification controls across email, push, in-app, and private messages; one-click unsubscribe that mailbox providers now expect; bounce and complaint suppression; and privacy export/erasure — the three things customers, auditors, and deliverability teams ask us for. It replaces an estimated multi-sprint build with a dependency, and because it is one preferences store rather than four per-surface opt-outs, it also settles the "why do forum emails ignore my email settings?" class of complaint. The trade-offs are honest: it is v0.1.0, audit logging is explicitly deferred to a future package, and there is no retention rule, so those become named roadmap items rather than hidden gaps.

For engineering: The surface is small and conventional — one table, one model, NotificationChannel and PreferenceSource enums, a Preferences service, and a category registry where first registration wins so the host can override any package's category. Defaults are "on unless the category says otherwise or a resolver answers per person," resolution is one read per person forgotten at every queue job (no stale worker reads), and a PreferenceChanged event fires on stored-value changes so you can sync legacy columns. Suppression is a contract — bind your own and your rules win. Bridges bind only after all providers boot and only while the sibling's own default is still bound, so a host binding always takes precedence; bridges.push, .forums, and .messages switch each off. Unsubscribe routes are opt-in, signature-verified, with optional TTL and a replaceable view.

Framing the risks: Pin the version and treat the API as provisional. Two behaviors will surprise a team porting from the original site: unregistered categories now throw instead of defaulting to "on," and unsubscribe endpoints live outside the web group. Both are improvements; both need a call-site audit. And be explicit that audit logging and retention are out of scope by design, so no one assumes "privacy contributor" means "audit-ready."