notification

package
v1.9.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 19 Imported by: 0

README

notification

Maps auth lifecycle events onto templated, localised notifications and dispatches them.

Where email builds a message and sends it, this plugin looks up a mapping, resolves a template and a locale, and hands the result to the dispatcher. That buys you channels beyond email, per-locale content, and the ability to switch off a single notification by nulling its mapping without touching code.

It can dispatch asynchronously, which keeps a slow provider off your signup latency.

Use it when

  • You ship in more than one language
  • You want notifications on channels other than email, push or in-app or SMS
  • You need to disable or re-point one specific message without a release

Skip it when

  • You need one welcome email in one language. email does that with a third of the setup
  • You have no template system wired. This plugin resolves templates, it does not author them
  • You are already running email. Pick one, or both will fire on the same hook

Wiring

authsome.WithPlugin(notification.New(notification.Config{
    AppName:       "My App",
    BaseURL:       "https://example.com",
    DefaultLocale: "en",
    Async:         true,
})),

Config

Field Type Default What it does
AppName string AuthSome Name available to templates
BaseURL string empty Root URL for building links
EmailVerifyPath string /verify-email Page where a user enters their verification code. The recipient email is appended as ?email=
PasswordResetPath string /reset-password Reset page. The token is appended as ?token=
SignInPath string /sign-in Sign-in page, used for login_url in the welcome message
DefaultLocale string en Locale used when the user has no preference
Async bool false Dispatch in the background where a dispatcher is available
Mappings map[string]*Mapping defaults Override hook-to-notification mapping. A nil entry disables that notification

The three path fields exist because the default templates expect a URL even when the flow delivers a code. They are how verify_url and reset_url get synthesised.

Settings

Key Default
notification.app_name AuthSome
notification.base_url empty
notification.default_locale en
notification.async false

Lifecycle hooks

Hook What happens
AfterSignUp Dispatches the welcome and verification notifications
AfterUserCreate Dispatches the welcome notification for a user created outside signup

email is the simpler alternative. waitlist contributes its own mappings here for approval and rejection messages.

Documentation

Overview

Package notification provides a Herald-backed notification plugin for AuthSome.

The plugin subscribes to authsome lifecycle hooks and maps them to Herald notification templates. It replaces the legacy email plugin with a unified multi-channel notification system.

contract.go: Wires the notification plugin into the forge-dashboard contract surface via plugin.ContractContributor.

Index

Constants

This section is empty.

Variables

View Source
var (
	// SettingAppName controls the application name used in notification templates.
	SettingAppName = settings.Define("notification.app_name", "AuthSome",
		settings.WithDisplayName("Application Name"),
		settings.WithDescription("Application name used in notification templates"),
		settings.WithCategory("Notifications"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithPlaceholder("My App"),
		settings.WithHelpText("Used in notification templates for branding"),
		settings.WithOrder(10),
	)

	// SettingBaseURL controls the application root URL for notification links.
	SettingBaseURL = settings.Define("notification.base_url", "",
		settings.WithDisplayName("Base URL"),
		settings.WithDescription("Application root URL for building links in notifications"),
		settings.WithCategory("Notifications"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithPlaceholder("https://example.com"),
		settings.WithHelpText("Used to build action links in notifications"),
		settings.WithOrder(20),
	)

	// SettingDefaultLocale controls the default locale for notifications.
	SettingDefaultLocale = settings.Define("notification.default_locale", "en",
		settings.WithDisplayName("Default Locale"),
		settings.WithDescription("Default locale for notification templates"),
		settings.WithCategory("Notifications"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithPlaceholder("en"),
		settings.WithHelpText("Language/locale for notification content. Default: en"),
		settings.WithOrder(30),
	)

	// SettingAsync controls whether notifications are sent asynchronously.
	SettingAsync = settings.Define("notification.async", false,
		settings.WithDisplayName("Async Delivery"),
		settings.WithDescription("Send notifications asynchronously via dispatch queue"),
		settings.WithCategory("Notifications"),
		settings.WithScopes(settings.ScopeGlobal),
		settings.WithHelpText("When enabled, notifications are queued for async delivery"),
		settings.WithOrder(40),
	)
)

Functions

func DefaultMappings added in v1.9.0

func DefaultMappings() map[string]*Mapping

DefaultMappings returns the default hook-to-notification mappings. These map authsome lifecycle events to Herald template slugs.

Skipped hooks (low-value or admin-only): auth.signout, auth.refresh, session.create, org.update, org.invitation.decline, org.team.*, webhook.*, rbac.role.create/update/delete, environment.*.

Types

type Config

type Config struct {
	// AppName is used in notification template data (e.g. "My App").
	AppName string

	// BaseURL is the application root URL for building links in notifications
	// (e.g. "https://example.com").
	BaseURL string

	// EmailVerifyPath is the path (relative to BaseURL) of the page where a
	// user enters their email-verification code. It is used to synthesize the
	// verify_url template variable for the email-verification notification
	// (the default Herald template requires verify_url even though the OTP
	// flow delivers a code rather than a link). Defaults to "/verify-email".
	// The recipient's email is appended as an ?email= query parameter.
	EmailVerifyPath string

	// PasswordResetPath is the path (relative to BaseURL) of the reset-password
	// page. It is used to synthesize the reset_url template variable for the
	// password-reset notification (the default Herald template requires
	// reset_url). Defaults to "/reset-password". The reset token is appended as
	// a ?token= query parameter.
	PasswordResetPath string

	// SignInPath is the path (relative to BaseURL) of the sign-in page. It is
	// used for the login_url in the welcome notification. Defaults to
	// "/sign-in".
	SignInPath string

	// DefaultLocale is the default locale for notifications (e.g. "en").
	// If empty, defaults to "en".
	DefaultLocale string

	// Async controls whether notifications are sent asynchronously via
	// Dispatch (if available). Defaults to false (synchronous).
	Async bool

	// Mappings overrides the default hook-to-notification mappings.
	// Nil entries disable the corresponding hook notification.
	Mappings map[string]*Mapping
}

Config configures the notification plugin.

type Mapping added in v1.9.0

type Mapping struct {
	// Template is the Herald template slug (e.g. "auth.welcome").
	Template string

	// Channels lists the channels to send on (e.g. ["email", "inapp"]).
	Channels []string

	// Enabled controls whether this mapping is active. Defaults to true
	// when the mapping is present.
	Enabled bool
}

Mapping describes how a hook action maps to a Herald notification.

type Plugin

type Plugin struct {
	// contains filtered or unexported fields
}

Plugin is the Herald-backed notification plugin. It replaces the legacy email plugin with a unified multi-channel notification system.

func New added in v1.9.0

func New(cfg ...Config) *Plugin

New creates a new notification plugin with optional configuration.

func (*Plugin) DeclareSettings added in v1.9.0

func (p *Plugin) DeclareSettings(m *settings.Manager) error

DeclareSettings implements plugin.SettingsProvider.

func (*Plugin) Name added in v1.9.0

func (p *Plugin) Name() string

Name returns the plugin name.

func (*Plugin) OnAfterSignUp added in v1.9.0

func (p *Plugin) OnAfterSignUp(ctx context.Context, u *user.User, _ *session.Session) error

OnAfterSignUp sends a welcome notification to the newly registered user.

func (*Plugin) OnAfterUserCreate added in v1.9.0

func (p *Plugin) OnAfterUserCreate(_ context.Context, _ *user.User) error

OnAfterUserCreate is intentionally a no-op for email verification.

The engine now owns verification issuance: SignUp (and ResendEmailVerification) mint a 6-digit OTP and fire ActionEmailVerificationRequested carrying the code, which handleHookEvent delivers. Sending here as well would double-email the user (and the old payload had no token/code, so the link was unusable).

func (*Plugin) OnInit added in v1.9.0

func (p *Plugin) OnInit(_ context.Context, engine plugin.Engine) error

OnInit extracts the Herald bridge and hook bus from the engine during initialization.

func (*Plugin) RegisterContract added in v1.9.0

func (p *Plugin) RegisterContract(
	d *dispatcher.Dispatcher,
	reg contract.Registry,
	wreg contract.WardenRegistry,
	engine plugin.Engine,
) error

func (*Plugin) SendInvitation added in v1.9.0

func (p *Plugin) SendInvitation(ctx context.Context, email, inviterName, orgName, acceptURL string) error

SendInvitation sends an organization invitation notification.

func (*Plugin) SendPasswordReset added in v1.9.0

func (p *Plugin) SendPasswordReset(ctx context.Context, email, name, resetURL string) error

SendPasswordReset sends a password reset notification. This is typically called by the engine's password reset flow.

Directories

Path Synopsis
Package contract wires the notification plugin's deep-link settings page into the forge-dashboard contract registry.
Package contract wires the notification plugin's deep-link settings page into the forge-dashboard contract registry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL