notify

Documentation

Overview

Package notify provides cross-platform OS notification support.

Example

Example demonstrates basic notification usage.

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/jongio/azd-core/notify"
)

func main() {
	// Create notifier with default config
	config := notify.DefaultConfig()
	notifier, err := notify.New(config)
	if err != nil {
		log.Fatalf("Failed to create notifier: %v", err)
	}
	defer func() { _ = notifier.Close() }()

	// Check if notifications are available
	if !notifier.IsAvailable() {
		fmt.Println("OS notifications not available")
		return
	}

	// Send a notification
	ctx := context.Background()
	notification := notify.Notification{
		Title:     "API Service",
		Message:   "Service has crashed",
		Severity:  "critical",
		Timestamp: time.Now(),
	}

	if err := notifier.Send(ctx, notification); err != nil {
		log.Printf("Failed to send notification: %v", err)
	}
}

Index

• Variables
• type Action
• type Config
  • func DefaultConfig() Config
• type Notification
• type Notifier
  • func New(config Config) (Notifier, error)

Examples

• Package
• Config
• Notification (WithActions)

Variables

var (
	ErrNotAvailable       = errors.New("OS notifications not available")
	ErrPermissionDenied   = errors.New("notification permissions denied")
	ErrNotificationFailed = errors.New("failed to send notification")
	ErrTimeout            = errors.New("notification timeout")
)

Error types - using errors.New for sentinel errors per Go 1.13+ best practices

Types

type Action

type Action struct {
	ID    string
	Label string
}

Action represents a notification action button.

type Config

type Config struct {
	// AppName is the application name shown in notifications
	AppName string

	// AppID is the platform-specific application identifier
	AppID string

	// Timeout for notification operations
	Timeout time.Duration
}

Config contains notification system configuration.

Example

ExampleConfig demonstrates custom configuration.

package main

import (
	"context"
	"log"
	"time"

	"github.com/jongio/azd-core/notify"
)

func main() {
	config := notify.Config{
		AppName: "My Custom App",
		AppID:   "com.mycompany.myapp",
		Timeout: 10 * time.Second,
	}

	notifier, err := notify.New(config)
	if err != nil {
		log.Fatalf("Failed to create notifier: %v", err)
	}
	defer func() { _ = notifier.Close() }()

	ctx := context.Background()
	notification := notify.Notification{
		Title:    "Custom App",
		Message:  "This is a custom notification",
		Severity: "info",
	}

	if err := notifier.Send(ctx, notification); err != nil {
		log.Printf("Failed to send notification: %v", err)
	}
}

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns default notification configuration.

type Notification

type Notification struct {
	// Title is the notification title (typically service name)
	Title string

	// Message is the notification body (status description)
	Message string

	// Severity indicates the notification severity
	Severity string // "critical", "warning", "info"

	// Timestamp when the notification was created
	Timestamp time.Time

	// Actions are optional actions the user can take
	Actions []Action

	// Data contains arbitrary data associated with the notification
	Data map[string]string

	// URL to open when notification is clicked (optional)
	URL string
}

Notification represents a notification to be displayed.

Example (WithActions)

ExampleNotification_withActions demonstrates notifications with action buttons.

package main

import (
	"context"
	"log"

	"github.com/jongio/azd-core/notify"
)

func main() {
	config := notify.DefaultConfig()
	notifier, err := notify.New(config)
	if err != nil {
		log.Fatalf("Failed to create notifier: %v", err)
	}
	defer func() { _ = notifier.Close() }()

	ctx := context.Background()

	notification := notify.Notification{
		Title:    "Service Error",
		Message:  "API service has stopped responding",
		Severity: "critical",
		Actions: []notify.Action{
			{ID: "view", Label: "View Dashboard"},
			{ID: "restart", Label: "Restart Service"},
			{ID: "dismiss", Label: "Dismiss"},
		},
		Data: map[string]string{
			"service": "api-service",
			"pid":     "12345",
		},
	}

	if err := notifier.Send(ctx, notification); err != nil {
		log.Printf("Failed to send notification: %v", err)
	}
}

type Notifier

type Notifier interface {
	// Send sends a notification to the OS notification system.
	Send(ctx context.Context, notification Notification) error

	// IsAvailable returns true if OS notifications are available and permitted.
	IsAvailable() bool

	// RequestPermission requests notification permissions from the OS.
	// Returns nil if permissions granted, error otherwise.
	RequestPermission(ctx context.Context) error

	// Close cleans up notification system resources.
	Close() error
}

Notifier is the interface for platform-specific notification systems.

func New

func New(config Config) (Notifier, error)

New creates a new platform-specific notifier.