toast

README

Toast

English | 简体中文

Toast is a small Go library for sending desktop notifications from native applications and lightweight tools. It supports macOS, Windows, and JavaScript WASM, with helper utilities for Windows toast click-to-focus workflows.

Features

• Simple toast.Push API with functional options
• macOS notifications through osascript or Objective-C
• Windows toast notifications through Windows Runtime APIs
• Windows protocol activation for clickable toast actions
• Optional Windows focus helper for bringing the originating terminal or app to front
• JavaScript/WASM notification support for browser environments

Install

go get github.com/hellolib/toast

Quick Start

package main

import "github.com/hellolib/toast"

func main() {
    _ = toast.Push("Build finished", toast.WithTitle("Agent Notify"))
}

Platform Examples

macOS

package main

import "github.com/hellolib/toast"

func main() {
    _ = toast.Push("Permission required",
        toast.WithTitle("Agent Notify"),
        toast.WithSubtitle("15:04:05"),
        toast.WithAudio(toast.Submarine),
    )
}

For Objective-C delivery:

_ = toast.Push("Task completed",
    toast.WithTitle("Agent Notify"),
    toast.WithObjectiveC(),
)

Windows

package main

import "github.com/hellolib/toast"

func main() {
    _ = toast.Push("Task completed",
        toast.WithAppID("agent-notify"),
        toast.WithTitle("Agent Notify"),
        toast.WithAudio(toast.Default),
        toast.WithLongDuration(),
    )
}

To add an image:

_ = toast.Push("Task completed",
    toast.WithTitle("Agent Notify"),
    toast.WithIcon(`C:\path\to\icon.png`),
)

JavaScript / WASM

package main

import (
    "fmt"

    "github.com/hellolib/toast"
)

func main() {
    _ = toast.Push("Saved",
        toast.WithTitle("WASM App"),
        toast.WithOnClick(func(event interface{}) {
            fmt.Println("clicked")
        }),
        toast.WithOnClose(func() {
            fmt.Println("closed")
        }),
    )
}

Windows Click-To-Focus

Windows toast clicks are delivered through activation. For ordinary Go command line tools, the practical approach is:

1. Ship a small GUI-subsystem helper executable.
2. Register a custom URL protocol that launches the helper.
3. Send the toast with WithActivationType("protocol").
4. Pass the protocol URI through WithActivationArguments.

This repository provides both the library API and a helper command for that flow. The helper is a separate executable so toast clicks do not flash a console window.

Library Usage

package main

import (
    "fmt"
    "os"

    "github.com/hellolib/toast"
)

func main() {
    focus, err := toast.PrepareFocusActivation(
        os.Getppid(),
        `C:\path\to\toast-focus-helper.exe`,
    )
    if err != nil {
        panic(err)
    }

    _ = toast.Push("Click to focus the current terminal",
        toast.WithAppID("agent-notify"),
        toast.WithTitle("Agent Notify"),
        toast.WithMessage(fmt.Sprintf("helper: %s", focus.Helper)),
        toast.WithActivationType("protocol"),
        toast.WithActivationArguments(focus.Arguments),
    )
}

PrepareFocusActivation checks explicit helper candidates first. If none are provided or found, it looks next to the current executable for conventional names:

• toast-focus-helper.exe
• toast-focus-helper-arm64.exe
• <app>-focus-helper.exe
• <app>-helper.exe

Demo Commands

cmd/toast-focus is a runnable demo that sends a clickable toast. It expects the helper binary to be in the same directory.

make build

Artifacts are written to dist/:

• toast-focus.exe
• toast-focus-helper.exe
• toast-focus-arm64.exe
• toast-focus-helper-arm64.exe

For applications that only need the helper binaries:

make build-helpers

Make Targets

make test                 # Run Go tests
make build                # Build all Windows demo/helper binaries
make build-helpers        # Build only Windows focus helpers
make build-windows-amd64  # Build Windows amd64 demo/helper
make build-windows-arm64  # Build Windows arm64 demo/helper
make clean                # Remove dist/

API Overview

Common options:

• toast.Push(message, opts...)
• toast.WithTitle(title)
• toast.WithMessage(message)
• toast.WithAudio(audio)

macOS options:

• toast.WithSubtitle(subtitle)
• toast.WithObjectiveC()

Windows options:

• toast.WithAppID(appID)
• toast.WithIcon(path)
• toast.WithIconRaw(bytes)
• toast.WithActivationType(kind)
• toast.WithActivationArguments(uri)
• toast.WithProtocolAction(label, uri)
• toast.WithLongDuration()
• toast.WithShortDuration()

Windows focus helpers:

• toast.FindFocusHelper(candidates...)
• toast.RegisterFocusProtocol(helperPath, protocol...)
• toast.PrepareFocusActivation(pid, helperCandidates...)
• toast.FocusActivationArguments(pid, protocol...)

JavaScript/WASM options:

• toast.WithIcon(url)
• toast.WithImage(url)
• toast.WithRequireInteraction(true)
• toast.WithOnClick(fn)
• toast.WithOnShow(fn)
• toast.WithOnClose(fn)
• toast.WithOnError(fn)

License

MIT

Documentation

Index

• Constants
• func FindFocusHelper(_ ...string) (string, error)
• func FocusActivationArguments(pid int, protocols ...string) string
• func Push(message string, opts ...NotificationOption) error
• func RegisterFocusProtocol(_ string, _ ...string) error
• type Audio
• type FocusActivation
  • func PrepareFocusActivation(_ int, _ ...string) (FocusActivation, error)
• type NotificationOption
  • func WithAudio(audio Audio) NotificationOption
  • func WithIcon(urlIcon string) NotificationOption
  • func WithImage(urlImage string) NotificationOption
  • func WithLang(lang string) NotificationOption
  • func WithMessage(msg string) NotificationOption
  • func WithNotificationID(tag string) NotificationOption
  • func WithOnClick(fn func(event interface{})) NotificationOption
  • func WithOnClose(fn func()) NotificationOption
  • func WithOnError(fn func()) NotificationOption
  • func WithOnShow(fn func()) NotificationOption
  • func WithRenotify(b bool) NotificationOption
  • func WithRequireInteraction(b bool) NotificationOption
  • func WithSilent(b bool) NotificationOption
  • func WithTextDirection(dir TextDirection) NotificationOption
  • func WithTimestamp(t time.Time) NotificationOption
  • func WithTitle(title string) NotificationOption
  • func WithVibrate(v []int) NotificationOption
• type TextDirection

Constants

const (
	// DefaultFocusProtocol is the protocol used by the bundled focus helper.
	DefaultFocusProtocol = "anfocus"
)

Functions

func FindFocusHelper

func FindFocusHelper(_ ...string) (string, error)

FindFocusHelper is only supported on Windows.

func FocusActivationArguments

func FocusActivationArguments(pid int, protocols ...string) string

FocusActivationArguments formats the URI passed to WithActivationArguments.

func Push

func Push(message string, opts ...NotificationOption) error

func RegisterFocusProtocol

func RegisterFocusProtocol(_ string, _ ...string) error

RegisterFocusProtocol is only supported on Windows.

Types

type Audio

type Audio string

type FocusActivation

type FocusActivation struct {
	Protocol  string
	Helper    string
	Arguments string
}

FocusActivation describes the protocol activation data used to focus the source window when a Windows toast is clicked.

func PrepareFocusActivation

func PrepareFocusActivation(_ int, _ ...string) (FocusActivation, error)

PrepareFocusActivation is only supported on Windows.

type NotificationOption

type NotificationOption func(*notification)

func WithAudio

func WithAudio(audio Audio) NotificationOption

WithAudio

The audio to play when displaying the notification

func WithIcon

func WithIcon(urlIcon string) NotificationOption

WithIcon

The URL of the image used as an icon of the notification

func WithImage

func WithImage(urlImage string) NotificationOption

WithImage

The URL of an image to be displayed as part of the notification

func WithLang

func WithLang(lang string) NotificationOption

WithLang

The language code of the notification

func WithMessage

func WithMessage(msg string) NotificationOption

WithMessage

The single/multi line message to display for the notification.

func WithNotificationID

func WithNotificationID(tag string) NotificationOption

WithNotificationID

The ID of the notification (if any)

func WithOnClick

func WithOnClick(fn func(event interface{})) NotificationOption

WithOnClick

A handler for the click event. It is triggered each time the user clicks on the notification.

func WithOnClose

func WithOnClose(fn func()) NotificationOption

WithOnClose

A handler for the close event. It is triggered when the user closes the notification.

func WithOnError

func WithOnError(fn func()) NotificationOption

WithOnError

A handler for the error event. It is triggered each time the notification encounters an error.

func WithOnShow

func WithOnShow(fn func()) NotificationOption

WithOnShow

A handler for the show event. It is triggered when the notification is displayed.

func WithRenotify

func WithRenotify(b bool) NotificationOption

WithRenotify

Specifies whether the user should be notified after a new notification replaces an old one

func WithRequireInteraction

func WithRequireInteraction(b bool) NotificationOption

WithRequireInteraction

indicating that a notification should remain active until the user clicks or dismisses it, rather than closing automatically.

func WithSilent

func WithSilent(b bool) NotificationOption

WithSilent

Specifies whether the notification should be silent — i.e., no sounds or vibrations should be issued, regardless of the device settings.

func WithTextDirection

func WithTextDirection(dir TextDirection) NotificationOption

WithTextDirection

The text direction of the notification

func WithTimestamp

func WithTimestamp(t time.Time) NotificationOption

WithTimestamp

Specifies the time at which a notification is created or applicable (past, present, or future).

func WithTitle

func WithTitle(title string) NotificationOption

WithTitle

The main title/heading for the notification.

func WithVibrate

func WithVibrate(v []int) NotificationOption

WithVibrate

Specifies a vibration pattern for devices with vibration hardware to emit.

type TextDirection

type TextDirection string

const (
	// Auto adopts the browser's language setting behavior (the default.)
	Auto TextDirection = "auto"
	// LTR left to right
	LTR TextDirection = "ltr"
	// RTL right to left
	RTL TextDirection = "rtl"
)