Help us shape the future of Go! Take the 2026 Go Developer Survey

notification

package
v1.9.0 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 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