notificationcenter

README

togo-framework/notification-center

In-app notification inbox for togo — the database channel + bell.

Install

togo install togo-framework/notification-center

The togo answer to Laravel's database notifications / an in-app notification bell. It complements notifications (which delivers to external providers like email/Slack/push) by storing a per-user inbox you can list, count, and mark read.

Usage

nc, _ := notificationcenter.FromKernel(k)

// Store a notification for a user.
nc.Notify(ctx, "user-1", notificationcenter.Notification{
    Type:      "comment",
    Title:     "New comment",
    Body:      "Sam replied to your post",
    ActionURL: "/posts/9",
    Data:      map[string]any{"post_id": 9},
})

unread := nc.UnreadCount("user-1")               // bell badge
items  := nc.List("user-1", notificationcenter.Filter{UnreadOnly: true})
nc.MarkRead(items[0].ID)
nc.MarkAllRead("user-1")
nc.Delete(items[0].ID)

REST API

The acting user is resolved from the X-User-Id header (or an auth claim on the context).

Method	Path	Description
GET	/api/notifications?unread=true	List the inbox (newest first)
GET	/api/notifications/unread-count	{ "count": N } for the bell
POST	/api/notifications/{id}/read	Mark one read
POST	/api/notifications/read-all	Mark all read
DELETE	/api/notifications/{id}	Delete one

Configuration

No required env. Storage defaults to a bounded in-memory store; swap a DB-backed implementation with nc.WithStore(myStore) (implements the Store interface). If a realtime broker is configured, wire Notify to publish so the bell updates live.

---

Premium sponsors

ID8 Media  ·  One Studio

_{Support togo — become a sponsor.}

Documentation

Overview

Package notificationcenter is an in-app notification inbox for togo — the "database channel" + bell that complements the notifications plugin (which delivers to external providers like email/Slack/push).

Store a per-user notification, list the inbox, count unread, and mark read/deleted. A current user is resolved from the request context (X-User-Id header or an auth claim).

nc, _ := notificationcenter.FromKernel(k)
nc.Notify(ctx, "user-1", notificationcenter.Notification{
    Type: "comment", Title: "New comment", Body: "Sam replied to you", ActionURL: "/posts/9",
})

Index

• func WithUser(ctx context.Context, userID string) context.Context
• type Filter
• type Notification
• type Service
  • func FromKernel(k *togo.Kernel) (*Service, bool)
  • func (s *Service) Delete(id string) bool
  • func (s *Service) List(userID string, f Filter) []*Notification
  • func (s *Service) MarkAllRead(userID string) int
  • func (s *Service) MarkRead(id string) bool
  • func (s *Service) Notify(ctx context.Context, userID string, n Notification) *Notification
  • func (s *Service) UnreadCount(userID string) int
  • func (s *Service) WithStore(store Store) *Service
• type Store

Functions

func WithUser

func WithUser(ctx context.Context, userID string) context.Context

WithUser stores the acting user on a context (for non-HTTP callers/tests).

Types

type Filter

type Filter struct {
	UnreadOnly bool
	Limit      int // 0 = default 50
	Offset     int
}

Filter narrows a List query.

type Notification

type Notification struct {
	ID        string         `json:"id"`
	UserID    string         `json:"user_id"`
	Type      string         `json:"type,omitempty"`
	Title     string         `json:"title"`
	Body      string         `json:"body,omitempty"`
	Data      map[string]any `json:"data,omitempty"`
	ActionURL string         `json:"action_url,omitempty"`
	Read      bool           `json:"read"`
	CreatedAt time.Time      `json:"created_at"`
	ReadAt    *time.Time     `json:"read_at,omitempty"`
}

Notification is a single inbox item for a user.

type Service

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

Service is the notification-center runtime stored on the kernel.

func FromKernel

func FromKernel(k *togo.Kernel) (*Service, bool)

FromKernel returns the notification-center Service.

func (*Service) Delete

func (s *Service) Delete(id string) bool

Delete removes a notification.

func (*Service) List

func (s *Service) List(userID string, f Filter) []*Notification

List returns a user's notifications, newest first.

func (*Service) MarkAllRead

func (s *Service) MarkAllRead(userID string) int

MarkAllRead marks every notification for a user read; returns how many changed.

func (*Service) MarkRead

func (s *Service) MarkRead(id string) bool

MarkRead marks a single notification read.

func (*Service) Notify

func (s *Service) Notify(ctx context.Context, userID string, n Notification) *Notification

Notify stores a notification for a user and returns the stored record. If a realtime broker is present on the kernel it is also published so a connected bell can update live.

func (*Service) UnreadCount

func (s *Service) UnreadCount(userID string) int

UnreadCount returns the number of unread notifications for a user.

func (*Service) WithStore

func (s *Service) WithStore(store Store) *Service

WithStore swaps the backing store (e.g. a DB-backed implementation).

type Store

type Store interface {
	Add(n *Notification)
	ByUser(userID string) []*Notification
	Get(id string) (*Notification, bool)
	Delete(id string) bool
}

Store is the persistence seam (swap the default in-memory store for a DB one).